release-openspec

OpenSpec のリリース

OpenSpec のリリースワークフローを、再開可能なステートマシンとして実行します。呼び出しのたびに GitHub の最新の状態を確認し、安全に実行できる次のアクションだけを行います。前回の呼び出しが完了したと想定してはいけません。

原則

• Fission-AI/OpenSpec と origin/main をリリースの信頼できる情報源として扱います。
• ユーザーがステータス、準備状況、またはアドバイスを求めた場合は、デフォルトで読み取り専用の監査を行います。
• リリース、リリースの準備、続行、または再開の依頼は、該当するリリースアクションを実行する承認として扱います。
• ユーザーのチェックアウトを維持します。変更セットを準備するためだけに、無関係な変更を破棄したり、現在のブランチを切り替えたりしてはいけません。
• チェックアウトに未コミットの変更がある場合、または main 以外のブランチにいる場合は、現在の origin/main から一時的なワークツリーを作成し、リリース用のコミットを作成します。
• 自分自身の PR を承認してはいけません。人間によるレビューは、意図的に設けられたゲートです。
• マージキューへの登録は中間状態であり、マージではありません。GitHub が mergedAt を報告し、そのコミットが main に存在することを確認してから次に進みます。
• 自動生成される Version Packages PR を手動で作成してはいけません。Changesets アクションが作成します。
• CI を再実行させるためだけに空のコミットをプッシュしてはいけません。まず失敗した実行、または実行が見つからない原因を調査します。
• 処理を一時停止する場合は、URL、到達した状態、必要な人間のアクションを明確に報告します。

2 種類の PR を区別する

出力と判断では、次の 2 種類を混同しないでください。

• Changeset PR：1 つ以上の .changeset/*.md ファイルを追加する、通常の人間が作成した PR です。機能追加や修正の PR に Changeset を追加することを優先してください。キャッチアップ用の Changeset PR は、すでにマージ済みでリリースに含めるべき作業がある場合にのみ作成します。
• Version Packages PR：自動生成される changeset-release/main の PR で、タイトルは chore(release): version packages です。Changeset を main にマージしたり、追加したりすると、同じ PR が更新されます。この PR をマージすると、安定版リリースが公開されます。

Version Packages PR が開いていても、キャッチアップ用の Changeset PR を作成することは禁止されません。ただし、監査でリリース対象として不足している作業が見つかった場合に限り、キャッチアップ用 PR が有用だということです。その PR がマージされたら、既存の Version Packages PR が更新されるのを待ちます。

リリース監査から始める

1. リポジトリとツールを確認します。

   • gh repo view --json nameWithOwner,url で GitHub リポジトリを解決します。
   • 書き込み操作の前に、認証済みの gh、git、pnpm が使用できることを必須とします。
   • 正規のリポジトリが Fission-AI/OpenSpec でない場合は、リリース変更を行う前に停止します。

2. 作業ツリーを変更せずに更新します。

   git fetch origin main
   

   無差別にすべてのタグをフェッチしないでください。このリポジトリには競合する古いローカルタグが含まれている場合があり、その場合、origin/main のフェッチには成功していても git fetch --tags は失敗することがあります。

3. 最新の安定版 GitHub リリースを探します。ドラフトとプレリリースは除外します。安定版の基準より新しいベータタグが存在する可能性があるため、git describe は使用しないでください。

   gh release list --repo Fission-AI/OpenSpec \
     --exclude-drafts --exclude-pre-releases --limit 100 \
     --json tagName,publishedAt \
     --jq 'max_by(.publishedAt) | {tagName, publishedAt}'
   

   git log の境界として使う前に、その安定版タグがローカルで解決できることを確認します。存在しない場合は、そのタグだけをフェッチします。同名のローカルタグが正規のリモートと一致しない場合は、不一致を報告し、別途解決した正規のコミットを使用します。監査の一環として、ユーザーのタグを強制的に書き換えてはいけません。

4. リリース関連のオープン PR を探します。

   gh pr list --repo Fission-AI/OpenSpec --state open \
     --head changeset-release/main \
     --json number,title,headRefName,baseRefName,url,reviewDecision,statusCheckRollup
   

   Version Packages PR は、タイトルだけでなく headRefName == "changeset-release/main" によって特定します。変更セット候補の PR は別途列挙し、そのファイルを確認します。.changeset/*.md への追加があることを必ず確認してください。Version Packages PR による変更セットの削除を、作成された変更セットと誤認しないでください。また、機能・修正 PR がリリース追跡情報を追加している場合があるため、タイトルだけに頼らないでください。

5. .changeset/README.md に記載された現在のリリースポリシー、origin/main 上の保留中の .changeset/*.md ファイル、および存在する場合は Version Packages PR の本文とファイルを読みます。

6. 最新の安定版タグ以降の first-parent コミットを一覧表示します。

   git log --first-parent --date=short \
     --pretty=format:'%h%x09%ad%x09%s' <stable-tag>..origin/main
   

7. リリース対象となるマージ済み PR を既存の変更セットに対応付けます。PR のファイルと変更セットの履歴を使い、表現が似ているだけで対象に含まれていると推測しないでください。

8. 監査結果を次のいずれかに分類します。

   • missing-tracking：このリリースを対象とするユーザー向けの変更に変更セットがありません。
   • awaiting-changeset-review：適切な変更セット PR がすでに存在します。
   • awaiting-merge-queue：承認済みの変更セットまたは Version Packages PR がキューに入っていますが、まだ main に反映されていません。
   • awaiting-version-update：必要な変更セットは main にありますが、Version Packages PR にまだ取り込まれていません。
   • awaiting-version-review：Version Packages PR は最新ですが、承認されていません。
   • ready-to-publish：Version Packages PR は最新で、承認済みかつチェックに合格しています。
   • publishing：Version Packages PR はマージ済みですが、成果物がそろっていません。
   • needs-finalization：npm、タグ、GitHub Release はそろっていますが、リリースノートが未加工のままです。
   • complete：パッケージ、タグ、GitHub Release、整形済みのリリースノートが一致しています。

安定版の基準、提案するバージョン、対象に含まれる変更、漏れの可能性、意図的に除外した内部作業やドキュメント作業、オープン PR、次のアクションを含む簡潔な監査結果を提示します。

変更セットの対象範囲を決める

マージ済みの PR すべてに変更セットが必要だと決めつけず、.changeset/README.md に従ってください。

リリース追跡の対象として選ばれた作業、特に以下を含めます。

• ユーザー向けの新機能やコマンド
• 重要な修正や緊急修正
• 破壊的変更や非推奨化
• ユーザーに見えるパフォーマンス改善

通常は、ドキュメントのみの作業、テスト、CI／ツール関連の作業、内部リファクタリングは除外します。ユーザーに見える変更かどうかが曖昧な場合は、黙って除外せず、その点を明示してください。曖昧さによってリリース対象範囲やセマンティックバージョンが大きく変わる場合に限り、ユーザーに確認してください。それ以外の場合は適切に判断し、PR レビューを承認の関門とします。

changeset PR を作成または続行する

missing-tracking の場合にのみ実行してください。

1. 未対応の作業をすでにカバーするオープンな changeset PR がある場合は、それを再利用します。headRefName、ヘッドリポジトリ、maintainerCanModify を確認し、そのブランチを所有するリポジトリから正確なヘッドブランチを一時的なワークツリーにフェッチして、そこで更新し、同じ PR のヘッドにプッシュします。ブランチに書き込みできない場合は停止してください。重複する PR や置き換え用のブランチは作成しないでください。

2. 作成に取りかかる直前に .changeset/README.md を読みます。

3. 適切な PR がない場合に限り、現在の origin/main から短い changeset-<scope> ブランチを作成します。オペレーターのチェックアウトを変更しないよう、一時的なワークツリーを使用します。

4. 一貫性のあるリリース単位ごとに changeset を 1 つ作成することを優先します。同じリリースに含める小さな項目をまとめて、追いつき用の changeset を 1 つ作成してもかまいません。

5. 正確なパッケージ名 "@fission-ai/openspec"、必要な中で最も高いセマンティックバージョンの更新、関連する見出しのみを使用し、ユーザー向けの説明を記述します。

6. プッシュ前に検証します。

   pnpm exec changeset status
   

7. コミットしてプッシュし、対象となったマージ済み PR と追いつき用の変更が必要な理由を本文に記載した PR を作成します。

8. PR の URL を返して、人間による承認を求めたら停止します。自分で承認しないでください。

後続の呼び出しでは、PR が承認済みでチェックがすべて成功している場合、ユーザーがリリースの続行または完了を依頼したときに限り、マージするかマージキューに追加します。GitHub がマージキューを使用している場合は、mergeQueueEntry、キューのチェック、mergedAt を確認し、PR が実際に main に反映されるまでは awaiting-merge-queue の状態を維持します。その後、main 上で Changesets アクションが既存の Version Packages PR を更新するのを待ちます。簡潔な進捗を伝えながら確認を続けてください。空のコミットや別のブランチ更新をプッシュしないでください。そうした操作は承認を取り消し、キューを再開させる可能性があります。

Version Packages PR を検証する

準備完了と判断する前に、以下を実施します。

1. main を対象とし、changeset-release/main から作成され、想定される自動化によって生成された PR であることを確認します。
2. 現在の main にある保留中の .changeset/*.md ファイルをすべて列挙します。ただし、.changeset/README.md は除外します。PR がすべてを取り込み、それぞれに対応する変更履歴の内容を含んでいることを確認します。保留中の changeset を延期すべき場合は停止してください。別途レビューされた変更として削除または修正し、自動化によって Version Packages PR が再生成されるのを待ってから続行します。
3. gh pr view で baseRefOid と headRefOid を取得し、baseRefOid が現在の origin/main と一致することを必須とします。両方のリビジョンについて、クリーンなデタッチ状態の一時的なワークツリーを作成します。ヘッドのオブジェクトがローカルにない場合は、最初に不変の pull/<number>/head ref をフェッチします。オペレーターの現在のワークツリーを使って検証しないでください。
4. ベースのワークツリーで pnpm exec changeset status --output changeset-status.json を実行し、そのファイルから想定されるパッケージとバージョンを読み取ります。Changesets CLI が使えない場合は、まず一時的なワークツリーにロック済みの依存関係をインストールします。
5. ベースのステータスと保留中の changeset 全体をヘッドのワークツリーと比較します。package.json、CHANGELOG.md、削除された changeset ファイル、PR 本文、提案されたバージョンがすべて一致している必要があります。ヘッドでは changeset がすでに取り込まれており、保留中のリリースを計算できないため、ベースからヘッドへの比較を行います。
6. 検証後に一時的なワークツリーを削除し、gh pr view／gh pr checks ですべての必須チェックとレビュー状況を確認します。

PR が最新で未承認の場合は、URL を返して人間による承認を待ちます。承認済みでチェックが成功している場合は、ユーザーがリリースまたは続行を依頼したときに限り、マージするかマージキューに追加します。マージキューが有効な場合、承認、自動マージの有効化、またはキューへの登録を、公開に進むための確定条件とみなさないでください。mergedAt と、マージが main に反映されたことの確認を待ちます。

安定版の公開を確認する

Version Packages PR がマージされた後：

1. マージコミットのリリースワークフローの実行を見つけ、完了を待ちます。
2. 次の3つの成果物を個別に確認します。
   • npm view @fission-ai/openspec@<version> version
   • リモートタグ v<version> が想定されるコミットを指していること。
   • gh release view v<version> が存在し、プレリリースではないこと。
   • リリースのアセットに、Binaries ワークフロー（binaries.yml）がリリース公開の約10分後に添付する8つの openspec-* スタンドアロンバイナリと SHA256SUMS が含まれていること。SHA256SUMS が揃うまでは、インストールスクリプトは以前のリリースをインストールし続けるため、ユーザーが利用可能なリリースを失うことはありません。
3. 一部の成果物しか存在しない場合は、部分的な状態を報告し、公開アクションを再試行する前に確認を再開します。npm にすでに存在するバージョンは、絶対に再公開しないでください。バイナリがない場合に npm での操作は必要ありません。workflow_dispatch とリリースタグを使って binaries.yml を再実行し、バイナリを添付してください。
4. すべての成果物が揃ったら、リリースノートのリファレンスを読み、GitHub Release を整え、保存されたタイトルと本文を確認します。

ベータ版を公開する

ユーザーがベータ版またはプレリリースを明示的に求めた場合に限り、この手順に進みます。

1. 同じ監査を実施し、保留中の changeset によって次の安定版が生成されることを確認します。
2. ベータ版の公開では changeset が消費されず、安定版の Version Packages PR も置き換わらないことを説明します。
3. 既存の release-prepare.yml ワークフローを main で実行します。ベータ版のバージョンをローカルで計算したり設定したりしないでください。
4. ワークフローで選択されたバージョン、npm の beta dist-tag、リモートタグ、プレリリースの GitHub Release を確認します。
5. ベータ版の依頼の一環として、安定版の Version Packages PR をマージしないでください。

失敗に対処する

• CI が失敗した場合は、再実行やコード変更を提案する前に、失敗したチェックとログを調べます。
• Version Packages PR が古くなっている場合は、まず、最新の changeset が main に到達した後に release-prepare.yml の push 実行が成功したことを確認します。
• ブランチの不一致がある場合は、Changesets アクションにブランチを更新させます。changeset-release/main を強制プッシュしないでください。
• PR がキューに入っている場合は、マージグループのチェックとキューの状態を調べます。正常に進行している間は、再登録、ブランチの更新、無関係なチェックの再実行を行わないでください。
• npm にすでに存在するバージョンの場合は、停止してタグ／GitHub Release を調整します。バージョンを暗黙的に繰り上げたり、再公開したりしないでください。
• GitHub の権限不足や必須レビューがある場合は、該当するゲートと URL を正確に報告します。次回の実行で状態を確認して再開できるよう、検出した状態を保持します。

完了レポート

次の項目を報告します。

• リリースしたバージョンと安定版／ベータ版のチャネル。
• 該当する場合は、changeset PR と Version Packages PR の URL。
• リリースワークフローの結果。
• npm パッケージ、タグ、GitHub Release の確認結果。
• リリースノートの最終調整状況。
• 意図的に保留した変更。