Руководство по циклу выпуска

Это руководство проводит выпуск vX.Y.Z для apothem от чистого рабочего дерева до проверенных поверхностей распространения. Процедура написана для сопровождающего, владеющего gh, git и консолью релиз-уровня; она завершается проверенной страницей Release, заполненным CHANGELOG и проверкой пути установки, подтверждающей, что каждая пользовательская поверхность отвечает на канонической команде установки.

Форма выпуска — один тег, два этапа. Один подписанный тег выпуска на main запускает .github/workflows/release.yml, который собирает, подписывает, аттестует и публикует GitHub Release с полным набором артефактов — sdist, wheel, CycloneDX SBOM, бандлы Sigstore cosign, происхождение SLSA-3 и архивы платформенной среды выполнения. Необязательный второй этап — ручной запуск publish-npm.yml, который публикует @ahmed-g-gad/apothem на npmjs.com после того, как scripts/release/check-release-ready.sh становится зелёным. Версионный раздел CHANGELOG создаётся вместе с коммитом тега; оператор запускает проверку пути установки после того, как оба этапа завершены.

1. Предварительные условия

Сопровождающий подтверждает следующее перед тегированием:

• Рабочее дерево. Чистое (git status не показывает ничего отложенного). Вся работа над функциями для выпуска находится на main.

• CI зелёный. Последний main gh run list --branch=main --limit=1 --json conclusion --jq '.[0].conclusion' возвращает success.

• Инструментарий. gh (GitHub CLI) версии 2.40 или новее, авторизованный в ahmed-g-gad; git 2.40 или новее с загруженным подключом подписи GPG; привязка доверенного издателя npm для @ahmed-g-gad/apothem действует (проверено согласно руководству по настройке аккаунта издателя).

• Якоря версий выровнены. Строка версии, объявленная в pyproject.toml, совпадает с планируемым тегом без префикса v. Проверьте:

  grep '^version' pyproject.toml

  Ожидаемый вывод (для выпуска vX.Y.Z; заполнители обозначают выпускаемый тег):

  version = "X.Y.Z"

• Раздел CHANGELOG подготовлен. CHANGELOG.md содержит версионный раздел под заголовками Keep-a-Changelog. Сопровождающий обновляет дату и релизные пункты в том же коммите, который содержит тег.

2. Тегирование и запуск

2.1 Создание релизного коммита

Релизный коммит содержит два изменения:

• Версионный раздел CHANGELOG.md с указанием фактической даты выпуска по UTC.
• Версия pyproject.toml поднята до новой версии (только когда предыдущий коммит на main уже содержит закрепление предыдущей версии и требуется свежее поднятие; коммит также может произойти во время цикла поднятия версии за несколько дней до времени тегирования).

Пример коммита:

git checkout main
git pull --ff-only origin main
# Author CHANGELOG and pyproject.toml edits via Edit tool, then:
git add CHANGELOG.md pyproject.toml
git commit -S -m "chore(release): cut vX.Y.Z"
git push origin main

Флаг -S подписывает коммит ключом GPG. Push запускает стандартную матрицу CI (lint, test, build); дождитесь зелёного перед тегированием.

2.2 Подпись и push тега

git tag -a -s vX.Y.Z -m "vX.Y.Z"
git push origin vX.Y.Z

Комбинация -a -s создаёт аннотированный тег с подписью GPG. Push запускает .github/workflows/release.yml, который собирает, подписывает, аттестует и публикует.

2.3 Подтверждение завершения релизного рабочего процесса

gh run watch $(gh run list --workflow=release.yml --limit=1 --json databaseId --jq '.[0].databaseId')

Рабочий процесс выполняет сборку (sdist + wheel), генерацию SBOM (CycloneDX), безключевую подпись cosign, генерацию и проверку происхождения SLSA-3, сборку платформенных архивов (darwin / linux / windows), подпись архивов с агрегированным манифестом SHA256SUMS и финальную публикацию GitHub Release. Сопровождающий просматривает журнал задания publish GitHub Release на предмет подтверждений загрузки активов.

2.4 Запуск публикации в npm (необязательный этап)

После того как GitHub Release и шлюз готовности стали зелёными:

bash scripts/release/check-release-ready.sh vX.Y.Z
gh workflow run publish-npm.yml --field tag=vX.Y.Z

Одобрите развёртывание среды npmjs, когда будет предложено. Рабочий процесс публикует @ahmed-g-gad/[email protected] на npmjs.com через npm Trusted Publishing (OIDC); в репозитории не хранится токен реестра.

3. Поверхности распространения

У каждой поверхности есть команда проверки, отвечающая на вопрос «приземлился ли выпуск здесь?»:

GitHub Release — это каноническая поверхность артефактов; пакет npm и скриптовые установщики — это пути установки, наложенные поверх него. Публикация в npm намеренно является последним этапом.

4. Дисциплина CHANGELOG

CHANGELOG.md содержит один раздел на выпуск согласно соглашению Keep-a-Changelog. Правка CHANGELOG в релизном коммите:

• Подтверждает, что версионный раздел использует заголовок ## [X.Y.Z] — YYYY-MM-DD.
• Подтверждает, что стандартные заголовки — Added, Changed, Deprecated, Removed, Fixed, Security — используются там, где это применимо. Пустые заголовки удаляются из отрендеренного файла.
• Фиксирует возможности, а не реализацию. Только доменный язык; никаких внутриплановых ссылок; никаких хешей коммитов; никаких идентификаторов плана или фазы.

Раздел CHANGELOG, переживший проверку сопровождающего, читается как якорь релизных заметок для нарратива анонса.

5. Проверка пути установки

После завершения обоих этапов сопровождающий запускает проверку. Проверка — это каноническое подтверждение того, что пользовательские команды установки отвечают.

5.1 Плагин Claude Code

/plugin marketplace add ahmed-g-gad/apothem
/plugin install apothem@apothem

Ожидается: плагин устанавливается, и команды apothem доступны внутри Claude Code.

5.2 Node.js (npx)

npx @ahmed-g-gad/[email protected] --version

Ожидаемый вывод: apothem X.Y.Z.

5.3 Одношаговый скриптовый установщик (POSIX)

curl -fsSL https://apothem.ahmedgad.com/install.sh | sh
apothem --version

Ожидаемый вывод: apothem X.Y.Z.

5.4 Одношаговый скриптовый установщик (Windows)

irm https://apothem.ahmedgad.com/install.ps1 | iex
apothem --version

Ожидаемый вывод: apothem X.Y.Z.

5.5 Проверка артефактов (свидетельство цепочки поставок)

gh release download vX.Y.Z --pattern 'apothem-X.Y.Z*' --pattern '*.cosign.bundle'
cosign verify-blob \
  --bundle apothem-X.Y.Z-py3-none-any.whl.cosign.bundle \
  --certificate-identity-regexp 'github.com/ahmed-g-gad/apothem' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  apothem-X.Y.Z-py3-none-any.whl
bash scripts/release/verify-provenance.sh vX.Y.Z

Ожидается: обе проверки завершаются с кодом 0.

Проверка выдаёт по одной строке PASS / FAIL на поверхность; записывайте строки в релизный журнал сопровождающего.

6. Восстановление после сбоев

У релизного рабочего процесса есть задокументированные режимы сбоев для релизного движка и издателя npm:

Если цикл восстановления не приземляет поверхность за один диагностический проход, поверхность регистрируется как известный сбой в релизных заметках со ссылкой на открытую задачу; пользователи направляются на рабочие поверхности, пока сломанная исправляется в патч-выпуске.

7. Перекрёстные ссылки

• Настройка издателя. Руководство по настройке аккаунта издателя устанавливает привязку доверенного издателя npm и предварительные условия на стороне GitHub, которые предполагает это руководство.
• Поток восстановления. Руководство по восстановлению выпуска (site/content/docs/runbooks/release-recovery.mdx) управляет межэтапным путём сбоя во время перехода выпуска, а не сбоями отдельных поверхностей, названными в §6.
• Включение Pages. Рабочий процесс publish-static-site.yml проверяет и развёртывает сайт проекта на пользовательском домене; руководство по включению Pages (site/content/docs/runbooks/pages-enablement.mdx) — это вышестоящая процедура, которая изначально установила пользовательский домен.
• Политика версионирования. site/content/docs/governance/release-engineering-policy.mdx содержит политику SemVer + подписи + устаревания, которую соблюдает это руководство.