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

Это руководство восстанавливает рабочее состояние, когда релиз vX.Y.Z репозитория ahmed-g-gad/apothem даёт сбой на полпути. Оно следует той же модели релизов, что и руководство по циклу релиза: аддитивной модели. Каждый релиз добавляет один коммит в main и один подписанный аннотированный тег; push тега запускает рабочие процессы релиза и npm. Ничего не отправляется через force-push, и история в main никогда не перезаписывается.

Опубликованная история постоянна. Каждый тег релиза, GitHub Release и версия npm, которые проект опубликовал, остаются опубликованными. Версии npm неизменяемы: опубликованный name@version никогда не может быть заменён, а номер версии, публикация которой была отозвана, никогда не может быть использован повторно. Поэтому восстановление движется вперёд с новым патч-релизом; оно не удаляет и не перенаправляет ничего, что пользователь мог уже установить.

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

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

2. Восстановление тегаCopy Anchor Link

Продиагностируйте тег:

git fetch origin --tags
git ls-remote origin refs/tags/vX.Y.Z
git cat-file -t vX.Y.Z      # "tag" for an annotated tag
git tag -v vX.Y.Z           # signature check

Что делать, зависит от того, было ли что-либо опубликовано из этого тега:

• Ещё ничего не опубликовано (рабочий процесс релиза дал сбой до своего задания публикации, и publish-npm.yml ничего не опубликовал): удалите тег и заново поставьте тег на тот же коммит с -a -s.

  Copy Text

  git push --delete origin vX.Y.Z
  git tag -d vX.Y.Z
  git tag -a -s vX.Y.Z -m "vX.Y.Z" <release-commit-sha>
  git push origin vX.Y.Z

• Что-либо опубликовано (GitHub Release с ресурсами или версия npm): никогда не перемещайте, не удаляйте и не используйте тег повторно. Исправьте вперёд с помощью vX.Y.(Z+1).

Имя тега никогда не используется повторно для другого коммита.

3. Восстановление публикаторовCopy Anchor Link

Каждый публикатор перезапускается отдельно:

4. ОткатCopy Anchor Link

Плохой релиз откатывается выпуском его исправления, а не его удалением:

1. Отмените проблемные коммиты в main (обычный коммит revert).

2. Выпустите vX.Y.(Z+1) по руководству по циклу релиза.

3. Пометьте плохую версию: добавьте заметку ### Yanked в её раздел CHANGELOG.md, отредактируйте заметки её GitHub Release так, чтобы они указывали на исправление, и пометьте её как устаревшую в npm:

   Copy Text

   npm deprecate @ahmed-g-gad/[email protected] "Contains <defect>; use X.Y.(Z+1)"

Плохой тег, GitHub Release и версия npm остаются опубликованными, поэтому закреплённые установки и воспроизводимые сборки продолжают разрешаться. Зафиксируйте откат как инцидент релиза.

5. Правило фасада релизаCopy Anchor Link

Правило фасада релиза репозитория (раздел «Release Facade» инструкций для участников) излагает описанную выше аддитивную модель: каждый опубликованный тег, GitHub Release и версия npm остаются опубликованными. Его требование показывать только текущую версию относится к тому, что говорят публичные поверхности. Это руководство никогда не удаляет и не перезаписывает опубликованный тег, GitHub Release или версию npm.

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

• Процедура релиза: руководство по циклу релиза.
• Политика релизов: политика инженерии релизов.
• Объекты тегов и способ проверки каждого из них: раздел о подписи релизов в SECURITY.md.
• Конфигурация Pages: site/content/docs/runbooks/pages-enablement.mdx.