Gentleman-Programming/release

使用するタイミング

このスキルは、gentle-pi リリースの準備、公開、検証を行う際に使用します。

厳格なルール

• ローカルマシンから gentle-pi を npm に公開しないでください。
• npm への公開は、GitHub Actions ワークフロー .github/workflows/publish.yml を経由する必要があります。これにより、証明書、環境保護、レジストリ認証情報が GitHub によって管理されます。
• 信頼されたワークフロー定義は保護されたデフォルトブランチ main からディスパッチし、リリースタグからは決してディスパッチしないでください。唯一の呼び出し元入力は正確な注釈付きバージョンタグです。
• リリースコミットにはクリーンな作業ツリーを使用してください。無関係なローカルファイルやスクラッチアーティファクトを含めないでください。
• レビュー結果は情報提供です。リリースの実施は通常のリポジトリポリシーに従い、RDD によってブロック、承認、または書き換えされてはなりません。
• リリースタグのターゲットをローカルの HEAD から推測しないでください。新しくフェッチした origin/main コミットとリポジトリの通常のリリースセーフガードを使用します。
• パッケージ検証をスキップしないでください。公開ワークフローでも検証は実行されますが、タグ付け前にローカルでの検証もパスする必要があります。

リリース手順

1. 状態を確認

   git status --short
   git fetch origin main --tags
   git log --oneline --decorate --max-count=5 origin/main
   

2. リリースコミットを準備

   • 意図した変更のみを適用します。
   • package.json のバージョンを次のセマンティックバージョンに上げます。
   • 依存関係の解決が実際に変わった場合を除き、ロックファイルの変更は含めないでください。

3. ローカルで検証

   pnpm test
   node scripts/verify-package-files.mjs
   npm pack --dry-run
   

   npm pack --dry-run は、公開パスに入らずにパッケージの内容とライフサイクルスクリプトを検証します。

4. コミットしてプッシュ

   git add <対象ファイル>
   git commit -m "<type(scope): リリース準備完了の変更>"
   git push origin HEAD:main
   git fetch origin main --tags
   

5. 正確なバージョンタグを作成して検証

   version="$(node -p "require('./package.json').version")"
   tag="v${version}"
   release_sha="$(git rev-parse 'origin/main^{commit}')"
   
   test "$(git rev-parse 'HEAD^{commit}')" = "${release_sha}"
   test -z "$(git ls-remote --tags origin "refs/tags/${tag}")"
   
   git tag -a "${tag}" "${release_sha}" -m "gentle-pi ${tag}"
   test "$(git rev-parse "${tag}^{commit}")" = "${release_sha}"
   
   git fetch origin main
   test "$(git rev-parse 'origin/main^{commit}')" = "${release_sha}"
   git push origin "refs/tags/${tag}"
   
   git fetch --no-tags origin "refs/tags/${tag}"
   test "$(git rev-parse 'FETCH_HEAD^{commit}')" = "${release_sha}"
   
   gh release create "${tag}" \
     --repo Gentleman-Programming/gentle-pi \
     --verify-tag \
     --title "gentle-pi ${tag}" \
     --notes "<リリースノート>"
   

   既存のバージョンを再タグ付けしたり上書きしたりしないでください。タグのターゲットは、ローカルのブランチではなく、新しくフェッチした不変の origin/main コミットから取得します。

6. GitHub Actions を通じて npm に公開

   version="$(node -p "require('./package.json').version")"
   tag="v${version}"
   gh workflow run publish.yml \
     --repo Gentleman-Programming/gentle-pi \
     --ref main \
     -f tag="${tag}"
   

   ワークフロー定義は常に保護されたデフォルトブランチ main から取得されます。これは1つの正確な vSemVer タグのみを受け入れ、リモートの注釈付きタグと現在のリモート main をフェッチし、展開されたタグコミット、ディスパッチ/main ワークフローコミット、チェックアウト、および package.json のバージョンが一致することを要求します。npm 公開の直前にリモートタグと main を再クエリし、dist-tag を内部で導出し、信頼できる OIDC と証明書を使用します。

   実行を監視し、失敗した場合はリリースを失敗として扱います:

   gh run list --repo Gentleman-Programming/gentle-pi --workflow publish.yml --limit 3
   gh run watch <run-id> --repo Gentleman-Programming/gentle-pi --exit-status
   

7. npm を検証

   npm view gentle-pi@<version> version --registry=https://registry.npmjs.org/
   npm dist-tag ls gentle-pi --registry=https://registry.npmjs.org/
   

障害処理

• 公開の失敗は通常のリポジトリポリシーに従って処理されます。これによってレビューの系列が再開されたり変更されたりすることはありません。

• ローカルで npm publish を試みたり再試行したりしないでください。同じタグが依然として現在のリモート main を対象としており、かつ障害が公開のみに起因する場合にのみ、信頼された main から再ディスパッチしてください。

• リモート main が進んだ場合、既存のタグを移動または再作成しないでください。新しいリリースコミット/バージョンを準備し、新しい注釈付きバージョンタグを作成してください。

• ワークフローが失敗した場合は、以下のコマンドでログを確認してください:

  gh run view <run-id> --repo Gentleman-Programming/gentle-pi --log
  

• ワークフロー成功後に npm の確認が一時的に古い場合は、公開失敗と見なす前に正確なバージョン (npm view gentle-pi@<version> version) を先に確認してください。

出力契約

以下の内容を報告してください:

• main にプッシュされたコミット SHA。
• 正確なバージョンタグとその展開されたコミット SHA。
• GitHub リリースの URL。
• 公開ワークフローの実行 URL と結果。
• npm の正確なバージョンと、ワークフローから導出された dist-tag (latest、beta、または next)。
• 残っているフォローアップや警告があれば。