릴리스 복구 런북

추가형 릴리스 모델에서 진행 도중 실패한 릴리스를 게시된 히스토리를 다시 쓰지 않고 단계별로 복구하는 절차입니다.

이 런북은 ahmed-g-gad/apothem의 vX.Y.Z 릴리스가 도중에 실패했을 때 동작 가능한 상태를 복원합니다. 이 런북은 릴리스 주기 런북과 같은 릴리스 모델, 즉 추가형 모델을 따릅니다. 각 릴리스는 main에 커밋 하나와 서명된 주석 태그 하나를 추가하며, 태그 푸시가 릴리스 워크플로와 npm 워크플로를 실행합니다. 어떤 것도 강제 푸시되지 않으며, main의 히스토리는 절대 다시 쓰이지 않습니다.

게시된 히스토리는 영구적입니다. 프로젝트가 게시한 모든 릴리스 태그, GitHub Release, npm 버전은 게시된 상태로 남습니다. npm 버전은 변경할 수 없습니다. 게시된 name@version은 절대 교체할 수 없으며, 게시가 취소된 버전 번호는 절대 다시 사용할 수 없습니다. 따라서 복구는 새 패치 릴리스로 앞으로 나아가며, 사용자가 이미 설치했을 수 있는 어떤 것도 삭제하거나 다른 대상을 가리키도록 바꾸지 않습니다.

1. 단계 분류

단계	작업	실패 모드	복구 경로
1	`main`에 릴리스 커밋을 안착시킨다(릴리스 주기 런북의 §2.1)	릴리스 커밋에서 CI가 실패한다	`main`에 또 다른 커밋을 올려 앞으로 고친다. CI가 녹색이 될 때까지 태그하지 않는다
2	서명된 주석 태그를 푸시한다	푸시가 거부되거나, 태그가 서명되지 않았거나 잘못된 커밋에 있다	아래 §2
3	`release.yml`이 GitHub Release를 빌드하고, 서명하고, 게시한다	작업이 실패하거나 자산이 누락된다	아래 §3
4	`publish-npm.yml`이 `@ahmed-g-gad/apothem`을 게시한다(같은 태그 푸시에서 실행됨)	게시가 실패한다	아래 §3
5	Pages와 저장소 메타데이터	사이트 또는 메타데이터가 최신이 아니다	아래 §3

모든 복구 작업은 멱등적입니다. 깨끗한 상태에서 실행하면 아무 일도 일어나지 않고, 부분적인 상태에서 실행하면 예상되는 단계 이후 조건이 복원됩니다.

2. 태그 복구

태그를 진단합니다.

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로 다시 태그합니다.
```
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. 게시자 복구

각 게시자는 개별적으로 다시 시도됩니다.

표면	진단	복구
릴리스 워크플로	`gh run view <run-id> --log`가 실패한 작업의 이름을 알려 준다	`gh run rerun <run-id> --failed`. `Check the plugin version changed with the plugin`에서의 실패는 버전이 올라가지 않았다는 뜻이다. 릴리스 주기 런북의 실패 표를 참조한다
GitHub Release	`gh release view vX.Y.Z --json tagName,isDraft,isPrerelease,assets`	`publish GitHub Release` 작업을 다시 실행한다. 이 작업은 기존 릴리스를 편집하고 `--clobber`로 자산을 다시 업로드한다
npm	`npm view @ahmed-g-gad/apothem version`과 `npx @ahmed-g-gad/[email protected] --version`	패키지의 npm Trusted Publishing을 확인한 뒤 `vX.Y.Z`에 대해 `publish-npm.yml`을 다시 실행한다(`gh workflow run publish-npm.yml --field tag=vX.Y.Z`). 버전이 이미 레지스트리에 있으면 워크플로는 게시를 건너뛴다. npm 버전은 변경할 수 없기 때문이다
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`로 해석되는지 검증한다
저장소 메타데이터	`gh repo view ahmed-g-gad/apothem --json description,homepageUrl,repositoryTopics,visibility`	설명, 홈페이지, 토픽을 제자리에서 패치한다. 저장소를 절대 다시 만들지 않는다

4. 롤백

잘못된 릴리스는 그 릴리스를 제거하는 것이 아니라 그 수정을 릴리스하는 방식으로 롤백합니다.

main에서 문제를 일으킨 커밋을 되돌립니다(일반적인 되돌리기 커밋).
릴리스 주기 런북에 따라 vX.Y.(Z+1)을 릴리스합니다.
잘못된 버전을 표시합니다. 해당 버전의 CHANGELOG.md 섹션에 ### Yanked 노트를 추가하고, 해당 버전의 GitHub Release 노트가 수정 버전을 가리키도록 편집하고, npm에서 해당 버전을 사용 중단(deprecate) 처리합니다.
```
npm deprecate @ahmed-g-gad/[email protected] "Contains <defect>; use X.Y.(Z+1)"
```

잘못된 태그, GitHub Release, npm 버전은 게시된 상태로 남으므로, 고정된 설치와 재현 가능한 빌드는 계속 해석됩니다. 롤백은 릴리스 인시던트로 기록합니다.

5. 릴리스 파사드 규칙

저장소의 릴리스 파사드 규칙(기여자 지침의 Release Facade 섹션)은 위의 추가형 모델을 명시합니다. 게시된 모든 태그, GitHub Release, npm 버전은 게시된 상태로 남습니다. 현재 버전만 나타내야 한다는 요건은 공개 표면이 말하는 내용에 적용됩니다. 이 런북은 게시된 태그, GitHub Release 또는 npm 버전을 절대 삭제하거나 다시 쓰지 않습니다.

6. 상호 참조

릴리스 절차: 릴리스 주기 런북.
릴리스 정책: 릴리스 엔지니어링 정책.
태그 객체와 각 객체를 검증하는 방법: SECURITY.md의 릴리스 서명 섹션.
Pages 구성: site/content/docs/runbooks/pages-enablement.mdx.

릴리스 복구 런북

1. 단계 분류Copy Anchor Link

2. 태그 복구Copy Anchor Link

3. 게시자 복구Copy Anchor Link

4. 롤백Copy Anchor Link

5. 릴리스 파사드 규칙Copy Anchor Link