リリースサイクルランブック

このランブックは apothem の vX.Y.Z リリースを、クリーンな作業ツリーから 検証済みの配布面まで駆動します。手順は gh、git、そして release-tier の シェルを操るメンテナー向けに書かれており、検証済みの Release ページ、提出済みの CHANGELOG、そして各ユーザー向け面が正規のインストールコマンドに応答することを 確認するインストールパスのスモークテストで終わります。

リリースの形態は単一タグ、二段階です。main 上の 1 つの署名済みリリース タグが .github/workflows/release.yml をトリガーし、それが GitHub Release を 完全な成果物セット——sdist、wheel、CycloneDX SBOM、Sigstore cosign バンドル、 SLSA-3 来歴、そしてプラットフォームランタイムアーカイブ——とともにビルド、署名、 証明、公開します。任意の第二段階は publish-npm.yml の手動ディスパッチで、 scripts/release/check-release-ready.sh がグリーンになった後に @ahmed-g-gad/apothem を npmjs.com へ公開します。バージョン付きの 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 署名サブキーをロード済み； @ahmed-g-gad/apothem の npm 信頼済みパブリッシャーバインディングが有効 （パブリッシャーアカウントセットアップランブック に従って検証済み）。

• バージョンアンカーの整合。 pyproject.toml で宣言されたバージョン文字列が、 v プレフィックスを除いて計画されたタグと一致する。検証：

  grep '^version' pyproject.toml

  期待される出力（vX.Y.Z リリースの場合；プレースホルダーは進行中のリリース タグを表す）：

  version = "X.Y.Z"

• CHANGELOG セクションのステージング済み。 CHANGELOG.md が Keep-a-Changelog の見出しの下にバージョン付きセクションを携える。メンテナーはタグを着地させる のと同じコミットで日付とリリース箇条書きを更新する。

2. タグ付けとトリガー

2.1 リリースコミットを執筆する

リリースコミットは 2 つの変更を着地させます。

• CHANGELOG.md のバージョンセクションに、リリースの実際の UTC 日付を付ける。
• pyproject.toml のバージョンを新バージョンへ引き上げる（main の前のコミット がすでに前バージョンのピンを携えており、新たな引き上げが必要な場合のみ； コミットはタグ時刻の数日前のバージョン引き上げサイクル中に着地することもある）。

コミット例：

git checkout main
git pull --ff-only origin main
# Edit ツールで CHANGELOG と pyproject.toml の編集を執筆し、その後：
git add CHANGELOG.md pyproject.toml
git commit -S -m "chore(release): cut vX.Y.Z"
git push origin main

-S フラグは GPG キーでコミットに署名します。プッシュは標準 CI マトリクス （lint、test、build）をトリガーします。タグ付け前にグリーンを待ってください。

2.2 タグに署名してプッシュする

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

-a -s の組み合わせは注釈付きで GPG 署名されたタグを生成します。プッシュは .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 環境デプロイメントを承認します。ワークフローは npm Trusted Publishing（OIDC）を介して @ahmed-g-gad/[email protected] を npmjs.com へ公開します。リポジトリにはレジストリトークンは保存されません。

3. 配布面

各面には「リリースはここに着地したか？」に答える検証コマンドがあります。

GitHub Release は正規の成果物面であり、npm パッケージとスクリプトインストーラーは その上に重ねられたインストールパスです。npm 公開は意図的に最後の段階です。

4. CHANGELOG の規律

CHANGELOG.md は Keep-a-Changelog 規約の下、リリースごとに 1 つのセクションを 携えます。リリースコミットの 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 で終了する。

スモークテストは面ごとに 1 行の PASS / FAIL を生成します。それらの行を メンテナーのリリースログに記録してください。

6. 障害からの回復

リリースワークフローには、リリースエンジンと npm パブリッシャーに対する文書化 された障害モードがあります。

回復サイクルが 1 回の診断パス内で面を着地させられない場合、その面は既知の障害 としてリリースノートにオープンな課題へのリンクとともに記録され、下流のユーザーは 壊れた面がパッチリリースで修正される間、動作する面へと案内されます。

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 + 署名 + 非推奨化のポリシーを携えています。