Руководство по восстановлению релиза

Процедуры восстановления для возврата репозитория в рабочее состояние, когда последовательность релиза прерывается на полпути, с поэтапной диагностикой.

Это руководство возвращает ahmed-g-gad/apothem в рабочее состояние, когда последовательность релиза по принципу «чистый лист на месте» прерывается на полпути. Публичный репозиторий не удаляется и не пересоздаётся во время релиза. Восстановление зависит от специфичного для релиза тега безопасности истории, локального клона сопровождающего и состояния нижестоящих менеджеров пакетов.

1. Таксономия этапов

Этап	Действие	Режим сбоя	Путь восстановления
1	Захватить и отправить тег безопасности истории	Тег отсутствует, не подписан или указывает на неверный граф	Пересоздать тег из точки слияния до squash перед перемещением `main`
2	Проверить CI, аудиторскую крепость, состояние пакетов и changelog	Любой шлюз не проходит	Остановитесь; исправьте локально; не перемещайте `main`
3	Переместить `main` на единственный подписанный коммит релиза	force-with-lease не проходит, коммит не подписан или сообщение коммита неверно	Сбросьте локальный `main` на предполагаемый подписанный коммит и повторите попытку со свежим lease
4	Опубликовать GitHub Release, Pages, npm и метаданные	Сбой публикатора или поверхности проверки	Сохраните коммит релиза; повторно запустите только сбойный публикатор после записи сбоя

Каждое действие восстановления идемпотентно. Запуск его на чистом состоянии — это no-op; запуск его на частичном состоянии восстанавливает ожидаемое послеэтапное условие.

2. Восстановление тега безопасности

Проверьте тег безопасности перед любой перезаписью истории:

git fetch origin --tags
git show --summary --show-signature <history-safety-tag>
git merge-base --is-ancestor origin/main <history-safety-tag>

Ожидается: тег существует, проверка подписи успешна, когда тег подписан, и полный граф до squash достижим из тега. Если тег отсутствует локально, но присутствует на удалённой стороне, заберите его. Если он отсутствует на удалённой стороне, остановите релиз и пересоздайте его перед тем, как трогать main:

git tag -s <history-safety-tag> <pre-squash-commit>
git push origin <history-safety-tag>

3. Восстановление основной ветки

Продиагностируйте состояние публичного main:

gh api repos/ahmed-g-gad/apothem/commits/main \
  --jq '.sha, .commit.message, .commit.verification.verified, .commit.verification.reason'

Ожидается после переключения: сообщение в точности равно release: Apothem <release-version>, а verification.verified равно true.

Если push с force-with-lease завершился неудачей до изменения GitHub, оставьте удалённую сторону как есть, заберите её, перестройте подписанный коммит релиза локально и повторите попытку только после того, как lease совпадёт:

git fetch origin main
git push --force-with-lease=main:<expected-remote-sha> origin main

Если push приземлился с неподписанным или непроверенным коммитом, исправьте локальную конфигурацию подписи, заново создайте коммит релиза из того же дерева и снова выполните force-push с lease. Не удаляйте тег безопасности.

4. Восстановление публикаторов

Каждый публикатор повторно запускается независимо после того, как коммит релиза GitHub проверен:

Поверхность	Диагностика	Восстановление
GitHub Release	`gh release view <release-tag> --json tagName,isDraft,isPrerelease,assets`	Удалите только некорректный черновик; в противном случае загрузите недостающие ресурсы с помощью `gh release upload --clobber`
Тег релиза	`git ls-remote origin refs/tags/<release-tag>` и `git tag -v <release-tag>`	Перетегируйте от того же SHA с `-a -s`, если тег отсутствует или не подписан; никогда не используйте имя тега повторно для другого коммита
npm	`npm view @ahmed-g-gad/apothem version` и `npx @ahmed-g-gad/apothem@<version> --version`	Повторно запустите `publish-npm.yml` для `<release-tag>` после подтверждения npm Trusted Publishing для `@ahmed-g-gad/apothem`
Pages	`gh run list --workflow=publish-static-site.yml --limit=1` и `curl -sSI https://apothem.ahmedgad.com/`	Повторно запустите `publish-static-site.yml`; проверьте, что CNAME всё ещё разрешается в `ahmed-g-gad.github.io`
Метаданные GitHub	`gh repo view ahmed-g-gad/apothem --json description,homepageUrl,repositoryTopics,visibility`	Пропатчите описание, домашнюю страницу и темы на месте; не пересоздавайте репозиторий

5. Откат

Откат — это крайняя мера. Сначала предпочтите целевое восстановление публикаторов. Если единственный коммит релиза необходимо отменить, восстановите main из тега безопасности:

git fetch origin --tags
git switch main
git reset --hard <history-safety-tag>
git push --force-with-lease origin main

После отката повторно запустите CI, повторно примените защиту ветки, если GitHub сообщает о дрейфе, и зафиксируйте откат как инцидент, блокирующий релиз. Сохраняйте тег релиза, только если артефакты релиза остаются валидными; в противном случае удалите некорректный релиз и тег перед повторной попыткой.

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

Конфигурация Pages: site/content/docs/runbooks/pages-enablement.mdx.
Процедура релиза: site/content/docs/runbooks/release-cycle.mdx.
Рецепты упаковки: packaging/README.md.
Якорь восстановления: специфичный для релиза тег безопасности истории.