zoryn up¶

Автоматическое обновление пакета до новой upstream-версии. Конвейер с сохранением состояния — можно приостановить, возобновить и откатить.

Использование¶

zoryn up [-t|--tarball] [--tag TAG] [--allow-unrelated-histories] [-f|--force]
         [--reset-to-gear]
         [-r|--rebuild] [--top] [--switch-to-upstream-git]
         [--sandbox=RUNNER] [--no-sandbox]
         [-b|--builder PATTERN] [-a|--arch ARCH] [-B|--branch BRANCH]
         [-p|--parallel] [-s|--sequential] [--fail-if-busy] [--skip-busy]
         [--skip-check[=LIST]] [--batch-pkgs=PKGS] [-d] [-v]

Опции¶

-t, --tarball — принудительный режим tarball (скачивание вместо git merge).
--tag TAG — использовать указанный upstream-тэг (пропустить автоопределение версии).
--allow-unrelated-histories — слияние несвязанных историй (для пакетов с импортированным чистым upstream).
-f, --force — принудительное обновление с пререлиза на стабильный релиз, когда нет новой версии.
--reset-to-gear — перед обновлением принудительно сбросить пакет к его состоянию, опубликованному в репозитории ALT. Отбрасывает локальные расхождения, незакоммиченные изменения, отставание/опережение и неотслеживаемые файлы (игнорируемые артефакты сборки сохраняются), затем настраивает remote gitery и сбрасывает ветку, запланированную для обновления — текущую, если это известная ветка ALT (sisyphus, p11, …), иначе sisyphus — независимо от того, какая ветка сейчас активна. Для пакетов, ещё не зарегистрированных в RDB, пропускается с предупреждением. Действует только при обычном запуске (стадия detect); игнорируется с --continue/--abort и с --stage/--from после detect. Удобно, чтобы начать обновление с чистого опубликованного состояния.
-b, --builder PATTERN — выбрать билдеры по имени или паттерну (см. Паттерны билдеров).
-a, --arch ARCH — выбрать билдер по архитектуре (через запятую для нескольких).
-B, --branch BRANCH — выбрать билдер по ветке (через запятую).
-p, --parallel — параллельная сборка при нескольких билдерах.
-s, --sequential — последовательная сборка (переопределяет parallel = on).
--fail-if-busy — завершить с ошибкой, если билдер занят (по умолчанию: ждать).
--skip-busy — пропускать занятые билдеры без ошибки.
--skip-check[=LIST] — пропустить проверки (через запятую). Значения: rpmbuild (пропустить %check), имена инструментов (sisyphus_check), all. Без значения — пропускает всё.
--batch-pkgs=PKGS — собрать только указанные batch-значения (через запятую) вместо всех значений из [batch].
-r, --rebuild — использовать hsh-rebuild вместо hsh (пересборка в существующем hasher без пересоздания chroot).
--top — интерактивный TUI для мониторинга сборок (в стиле htop).
--switch-to-upstream-git — миграция tarball-репозитория на схему upstream-git (см. ниже).
--sandbox=RUNNER — бэкенд песочницы для хуков: hybrid (по умолчанию), bwrap или direct.
--no-sandbox — отключить песочницу для хуков.
--no-python-auto-deps — отключить автообновление pyproject_deps.json и повтор сборки при изменении Python-зависимостей.
-v, --verbose — показывать вывод сборки на экран (в дополнение к лог-файлу).

Управление конвейером¶

Если стадия упала, можно возобновить, откатить или запустить изолированно:

Флаг	Описание
`--continue`	Возобновить с последней упавшей стадии
`--abort`	Откатить изменения к состоянию до обновления
`--restart`	Сбросить сохранённое состояние, начать заново
`--stage=STAGE`	Запустить одну стадию изолированно
`--from=STAGE`	Запустить с указанной стадии до конца

Доступные стадии: detect, fetch, find-version, merge, merge-hooks, spec, gear-tags, up-hooks, build, batch-build.

Состояние конвейера хранится в активной git-директории — .git/zoryn-up-state.json в обычном клоне или .git/worktrees/<name>/zoryn-up-state.json внутри git worktree — так что каждый worktree продолжает свой конвейер независимо.

Поддерживаемые схемы репозиториев¶

zoryn автоматически распознаёт четыре схемы ведения.

1. Git merge (стандартная)¶

Рабочее дерево содержит исходный код upstream плюс файлы ALT Linux (.gear/, .spec). Примеры: php, curl, nginx.

.gear/rules: tar: v@version@:.

Код upstream сливается в рабочее дерево. Патчи — коммиты поверх upstream. При обновлении git merge интегрирует новую версию с локальными изменениями.

2. Скачиваемый tarball¶

Upstream-тарболл скачивается и распаковывается в подкаталог. Файлы ALT Linux (.spec, .gear/, патчи) рядом. Используется с zoryn up --tarball или автоопределяется по watch-файлу.

.gear/rules: tar: @name@
             copy?: *.patch

Тарболл скачивается с upstream URL из watch-файла и импортируется в подкаталог.

3. Чистый tarball + подшивка истории¶

Рабочее дерево содержит только файлы ALT Linux (.spec, .gear/, *.patch). Исходный код upstream существует только в истории git, подшитой через merge. Примеры: libssh2, openssl.

.gear/rules: tar: @name@-@version@:.
             copy?: *.patch

При обновлении zoryn использует git merge -s ours — подшивает историю upstream без изменения файлов рабочего дерева. Патчи поддерживаются вручную.

Определение автоматическое: zoryn сравнивает файлы в HEAD и в upstream-тэге. Если нет общих исходных файлов (только .spec, .patch, .gear/), определяется схема «чистый tarball» и используется -s ours.

Импорт без общей истории. Когда локальная ветка не имеет общего предка с upstream (например, свежий импорт upstream-исходников), используйте --allow-unrelated-histories. Это merge с -s ours --allow-unrelated-histories, затем восстанавливает файлы upstream, сохраняя ALT-специфичные каталоги (.gear/, каталог spec, каталоги из copy в .gear/rules).

4. Subtree¶

Исходный код upstream — в подкаталоге, файлы ALT Linux — в корне. Пример: apache2-mod_auth_openidc.

.gear/rules: tar:  v@version@:.
             diff: v@version@:. mod_auth_openidc/

Директива diff: указывает gear создавать патч из различий между тэгом и подкаталогом. При обновлении zoryn использует git subtree pull. Локальные изменения в подкаталоге автоматически становятся патчами.

Определение автоматическое: zoryn анализирует историю коммитов каждого подкаталога. Если недавние коммиты преимущественно в стиле "Merge commit 'HASH'" (характерно для git subtree pull --squash), определяется subtree.

Последовательность действий¶

Находит spec-файл и извлекает текущую версию.
Синхронизирует локальный клон с публичным зеркалом ALT (git.altlinux.org/gears/<x>/<pkg>.git или srpms/), используя имя текущей локальной ветки как имя ref'а на зеркале. Срабатывает только когда локальная ветка — известная ветка ALT (sisyphus, p11, p10, c10f2, …); тематические ветки (master, wip-*, feature-*) тихо пропускаются с пояснительной строкой. При отставании делает fast-forward; при расхождении историй выполняет автоматический merge. Также пропускается, если пакет ещё не в RDB, рабочее дерево «грязное», HEAD отсоединён или fetch не удался. Прерывает конвейер при жёстких сбоях синхронизации (неразрешимые конфликты merge или отказ fast-forward), чтобы мейнтейнер устранил их до правки spec.
Проверяет, указывает ли URL: на pypi.org/project/<name>/ — если да, использует PyPI как источник версий (фильтрует отозванные/пре-релизные по PEP 440, создаёт alias-тэги при различии нормализации PEP 440 и git-тэга). --tag отключает обнаружение PyPI.
Читает URL репозитория из VCS: в spec-файле.
Добавляет upstream remote и получает тэги. URL может быть задан в .gear/upstream/remotes, в теге VCS: или в теге URL: spec-файла; берётся первый кандидат, который является известным публичным форжем (GitHub/GitLab/codeberg/sourcehut) или доступен через git ls-remote — так что самостоятельно развёрнутый Gitea/Forgejo/cgit тоже работает. Внутренние хосты ALT исключаются, чтобы собственный gear/srpm-репозиторий пакета не был ошибочно принят за upstream.
Применяет маппинг версий из .gear/version-up (если есть).
Находит более новые версии и выбирает последнюю.
Определяет стратегию merge (стандартная или -s ours).
Выполняет merge upstream-тэга (или скачивает тарболл с --tarball).
Запускает хуки из .gear/merge-up.d/.
Обновляет версию в spec, сбрасывает release в alt1.
Сканирует upstream changelog на CVE (если настроено).
Добавляет запись в changelog.
Запускает хуки из .gear/up.d/.
Обновляет gear-тэги.

Переход на схему upstream-git¶

--switch-to-upstream-git — это односторонняя миграция: пакет, ведущийся по tarball-схеме (схемы #2 или #3), переводится на стандартную схему git-merge (#1). После миграции рабочее дерево содержит исходный код upstream плюс .gear/, а каждый последующий zoryn up использует git merge вместо скачивания тарболла.

Быстрый старт¶

zoryn up --switch-to-upstream-git              # автоопределение upstream-тэга по текущему Version:
zoryn up --switch-to-upstream-git --tag v2007f # явно указанный тэг

Репозиторий должен быть чистым (без незакоммиченных изменений), а в spec-файле должен быть указан upstream git URL через тэг VCS: — например, VCS: https://github.com/owner/repo. Без VCS: команда откажется работать.

Что происходит, по шагам¶

Валидация. Команда отказывается работать в грязном рабочем дереве, в не-gear-каталоге и в репозитории, уже переведённом на upstream-git (определяется по наличию tar: @version@:. в .gear/rules).
Определение upstream URL. Читает тэг VCS: из spec-файла и нормализует его (удаляет завершающий .git, фрагменты и т. п.).
Разбор .gear/rules. По существующим директивам copy: / copy?: / patch: определяет, лежат ли altlinux-файлы в общем подкаталоге или в корне репозитория.
Перенос altlinux-файлов в .gear/.
- spec-файл переносится в .gear/<name>.spec.
- Старый .gear-rules переименовывается в .gear/rules.
- Патчи и прочие copy:-записи, которых ещё нет в .gear/, перемещаются туда (glob-шаблоны раскрываются предварительно).
- Если altlinux-файлы уже сложены в общий подкаталог, этот подкаталог сохраняется — переносятся только patch:-записи, лежащие за его пределами.
Коммит переносов. Создаётся единый коммит switch: move altlinux files to .gear/. Если файлы уже были в .gear/, шаг тихо пропускается.
Добавление remote upstream. Идемпотентно — если upstream уже указывает на правильный URL, шаг ничего не делает; если на другой URL, команда останавливается и сообщает, что remote нужно удалить вручную.
Получение веток и тэгов upstream.
Резолюция upstream-тэга.
- С --tag TAG тэг проверяется по списку полученных тэгов и используется как есть.
- Без --tag текущая Version: из spec сопоставляется с тэгами по той же эвристике, что и обычный zoryn up (учитываются префикс v, форма name-version, release_X_Y_Z и т. д.).
- При отсутствии совпадения команда печатает первые 15 доступных тэгов и завершается, чтобы вы могли перезапустить её с --tag.
Перезапись .gear/rules. Старая строка tar: заменяется на tar: <resolved-tag>:. (с сохранением подкаталога, если он был обнаружен); устаревшие copy: / patch:, ставшие лишними, удаляются.
Слияние истории upstream. Выполняется git merge --allow-unrelated-histories -s ours <tag>, затем upstream-файлы восстанавливаются в рабочее дерево, при этом .gear/ (и, если он есть, сохранённый подкаталог) остаются нетронутыми. Если merge падает, .gear/rules откатывается в предыдущее состояние, чтобы можно было устранить причину и перезапустить ту же команду.
Фиксация схемы. В секцию [merge] файла .gear/version-up записывается scheme = "git-merge", чтобы будущие zoryn up использовали git-merge даже до того, как тэги догонят новую раскладку.

Что происходит после успешной миграции¶

Если разрезолвленный upstream-тэг новее текущей Version: в spec, zoryn up продолжает обычным послемержным хвостом:

Version: в spec обновляется до новой версии, Release: сбрасывается в alt1.
Добавляется запись в changelog о смене версии.
gear-update-tag -a -c обновляет gear-тэги.
Пакет собирается на сконфигурированных билдерах; при успехе отправляется уведомление в desktop.

Если тэг совпадает с текущей версией, spec не трогается — выполняются только обновление gear-тэгов и пересборка.

Итоговая раскладка репозитория¶

После завершения команды:

Рабочее дерево заполнено исходниками upstream (из смерженного тэга).
Каталог .gear/ содержит spec-файл, rules, патчи и сохранённые copy-записи.
.gear/rules переписан в tar: <tag>:. (или tar: <tag>:. <subdir>/ для раскладок с подкаталогом).
Два новых коммита: switch: move altlinux files to .gear/ и merge-коммит, подшивающий историю upstream.
Remote upstream, указывающий на URL из VCS:.
В .gear/version-up записано [merge] scheme = "git-merge".

Пакет готов к zoryn submit после того, как вы пересмотрели git log --oneline -5 и убедились в успешности сборки.

Восстановление после сбоя миграции¶

Команда идемпотентна в части переноса файлов и настройки remote — если она упала на шаге merge, просто перезапустите её:

zoryn up --switch-to-upstream-git --tag <TAG>

Ранее выполненные перемещения и настройка remote будут обнаружены и пропущены; повторно выполняется только merge. Если хочется откатить миграцию полностью, используйте git reset --hard до коммита, предшествующего switch: move altlinux files to .gear/, и git remote remove upstream.

См. также¶

Конфигурация → .gear/version-up — настройка парсинга upstream-тэгов
Хуки — скрипты в .gear/merge-up.d/ и .gear/up.d/
Песочница — режимы изоляции хуков
zoryn submit — следующий шаг после успешного zoryn up