mcpField
R
release-plannotator

release-plannotator

github.com/backnotprop開発9.7k291 回インストール今日更新
リポジトリ

release-plannotator について

release-plannotatorは、Plannotatorのメンテナー向けにリリースノート作成からタグ付け、公開までを案内するスキルです。貢献者調査、バージョン更新、ビルド確認、公開前の検証を含みます。

主な機能

  1. 01変更内容と貢献者情報の収集
  2. 02レビュー用リリースノートの作成
  3. 03指定ファイルのバージョン更新
  4. 04依存順に沿ったビルド
  5. 05Pi拡張パッケージ内容の監査
  6. 06コミット、タグ付け、リリース公開

活用シーン

  1. 01新バージョンのノート作成
  2. 02複数パッケージのバージョン更新
  3. 03拡張機能のビルドと梱包内容の確認
  4. 04タグを起点とするリリースの実施

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/backnotprop/plannotator --skill release-plannotator

インストール後、Claude Code で/release-plannotatorを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
release-notes-v0.12.0.md
release-notes-v0.13.0.md
release-notes-v0.13.1.md

詳細

Plannotator のリリース

プロセスは4つのフェーズで構成されています。フェーズ1（リリースノート）が作業の大部分を占めます。後続のフェーズに進む前に、ドラフトを提示してレビューを受けてください。

フェーズ1：リリースノートのドラフト作成

これは最も重要なフェーズです。リリースノートは各バージョンの公開窓口であり、コミュニティが貢献を認めてもらうための主な手段です。

ステップ1：対象範囲を決める
  1. 最新のリリースタグを確認します：git tag --sort=-v:refname | head -1
  2. 新しいバージョン番号を決めます。不明な場合はユーザーに確認します（パッチ、マイナー、メジャー）。
  3. 最後のタグ以降の変更をすべて収集します：
    • コミット履歴には git log --oneline <last-tag>..HEAD
    • マージされた PR には git log --merges --oneline <last-tag>..HEAD
  4. 各 PR の詳細を取得するには、gh pr view <number> --json title,author,body,closedIssues,labels を使用します。
ステップ2：貢献者を調査する

これは重要です。リリースに参加したすべての人に謝意を示します。PR の作成者だけではありません。

各 PR と関連する issue について、以下を確認します：

  • PR の作成者 — コードを書いた人
  • Issue の報告者 — バグや機能リクエストを報告した人
  • Issue のコメント投稿者 — 有用な情報を添えて議論に参加した人
  • ディスカッションの作成者 — 関連する GitHub Discussions を開始した人
  • 機能リクエストの投稿者 — 関連する「closes #N」issue とその作成者を確認します

gh を使用して GitHub API から取得します：

# Get issue details including author
gh issue view <number> --json author,title,body

# Get issue comments to find participants
gh api repos/backnotprop/plannotator/issues/<number>/comments --jq '.[].user.login'

# Get PR review comments
gh api repos/backnotprop/plannotator/pulls/<number>/comments --jq '.[].user.login'
ステップ3：リリースノートを作成する

references/ にあるリリースノートの参考資料を読み、標準的なテンプレート構成を確認します。これらは過去のバージョンの実際のリリースノートです。文体、構成、詳しさを合わせてください。

  • release-notes-v0.13.0.md — 大規模リリース、14件の PR、初参加の貢献者3人、「New Contributors」＋説明形式の「Contributors」セクション
  • release-notes-v0.12.0.md — 大規模なコミュニティリリース、14件の PR（うち外部からの PR が10件）、詳しい説明形式の「Contributors」セクション
  • release-notes-v0.13.1.md — 小規模なパッチリリース、2件の PR、外部の作成者なし、issue の報告者に焦点を当てた「Community」セクション

参考資料ごとに、貢献者への謝意の示し方がどう異なるかに注意してください。リリースの貢献者の構成に合った形式を選びます。外部からの PR が多いリリースには説明形式の「Contributors」セクションが適しています。issue の報告が中心となったパッチリリースでは、より簡潔な「Community」セクションを使用します。

ファイルをリポジトリのルートに RELEASE_NOTES_v<VERSION>.md として保存します。

構成

  1. X/Twitter のフォローリンク — 1 行目に配置し、常に同じ内容にします：

    Follow [@plannotator](https://x.com/plannotator) on X for updates

  2. 「最近のリリースを見逃しましたか？」 の折りたたみ可能な表 — 前回のリリースノートからコピーし、次のようにします：

    • 直前のリリース（今回のリリースの一つ前）を最新の行として追加します
    • およそ 10〜12 行を維持し、必要に応じて最も古い行を削除します
    • 各行には、バージョンへのリンクと、機能の要点を短いフレーズでカンマ区切りにして記載します

  3. 「vX.Y.Z の新機能」 — リリースノートの中心となるセクションです

    • リリースのテーマと範囲を 1〜3 文で要約して書き出します。PR の数、外部コントリビューターによる PR の数、初参加のコントリビューターがいる場合はその人数にも触れます。
    • 主要な機能や修正ごとに、独立した ### サブセクションを設けます。各サブセクションには次を含めます：
      • 内容が分かる見出し（PR のタイトルをそのまま使わず、分かりやすく言い換えます）
      • 変更内容とその意義を説明する 1〜4 段落。具体的かつ明確に記述します。変更前にあった問題、変更による対応、ユーザーにとっての変化を説明します。
      • 末尾にクレジット行を記載します。PR へのリンク、closing [#N] 形式の関連 Issue へのリンク、コントリビューターのクレジットを含めます。
    • 小規模な変更は、太字のタイトルを付けた箇条書きとして ### 追加の変更 の下にまとめます。

  4. インストール／更新 — 前回のリリースノートを参照し、標準ブロックをそのまま再利用します

  5. 「変更内容」 — リリースに含まれるすべての PR を箇条書きにします：

    - feat: descriptive PR title by @author in [#N](url)

  6. 「新しいコントリビューター」 — 初参加のコントリビューターがいる場合：

    - @username made their first contribution in [#N](url)

  7. 「コントリビューター」または「コミュニティ」 — 参加者全員に謝意を示す説明セクションです：

    • PR の作成者については、何を実装したかを一文で説明します
    • Issue の報告者やコメント投稿者については、何を報告・議論したかを記載します
    • コミュニティからの Issue 報告者は、末尾に箇条書きでまとめます

  8. 変更履歴全体へのリンク：

    **Full Changelog**: https://github.com/backnotprop/plannotator/compare/<prev-tag>...<new-tag>
執筆ガイドライン
  • 情報を整理して伝える。 明快で読みやすい文章にします。宣伝文句や変更点の羅列ではなく、何が変わったのか、なぜ重要なのかを平易な言葉で説明します。
  • 必要なところで箇条書きを使う。 個別の項目（追加の変更、コントリビューター一覧など）には箇条書きを使い、機能の説明には段落を使います。
  • 決まり文句や流行語を使わない。 「エキサイティング」「画期的」「シームレス」「強力」などとは書きません。起きたことをそのまま説明します。
  • 気の利いた締めくくりを加えない。 セクションの最後に洒落た一言や要約の決め文句を置きません。機能そのものを説明してください。
  • 実用的なメリットを伝える。 何が変わり、ユーザーにとってどのような意味があるのかを、具体的かつ確かな表現で説明します。理想を語ったり、大げさに宣伝したりせず、実際の機能を記述します。
  • ダッシュを多用しない。 リリースごとに 1〜2 個なら問題ありません。続けて使っていることに気づいたら、文の構造を見直します。
  • 文法構造を大切にする。 文型に変化をつけ、能動態を使います。具体的な主語と動詞で記述します。
  • コントリビューターのメンション。 @username 形式のユーザー名をそのまま使い、[@user](url) のような Markdown リンクにしません。GitHub はリリースノート内の @mentions をアバターアイコン付きで表示します。コミュニティへの謝意を伝えるうえで重要です。
  • すべてのコントリビューターを記載する。 Issue を報告した人、判断に影響するコメントを残した人、議論に参加した人は、全員記載します。このプロジェクトの生命線はコミュニティです。
ステップ 4：レビュー用に提出する

下書きをリポジトリのルートにある RELEASE_NOTES_v<VERSION>.md に書き込み、ユーザーにレビューの準備ができたことを伝えます。このファイルは意図的に未追跡の状態にするため、git add やコミットは行いません。フィードバックを受け取るまでフェーズ 2 には進みません。

フェーズ 2：バージョンの更新

以下の7 ファイルのバージョン文字列を更新します（これらのみ。他の package.json ファイルではスタブバージョンを使用しています）。

ファイルフィールド
package.json（ルート）"version"
apps/opencode-plugin/package.json"version"
apps/pi-extension/package.json"version"
apps/hook/.claude-plugin/plugin.json"version"
apps/copilot/plugin.json"version"
openpackage.yml（ルート）version:
packages/server/package.json"version"

各ファイルを読み、現在のバージョンが想定どおりであることを確認してから、7 ファイルすべてを一括で更新します。

VS Code 拡張機能（apps/vscode-extension/package.json）はバージョンを個別に管理しているため、更新しないでください。

フェーズ 3：ビルド

依存関係の順にビルドを実行します。

bun run build:review    # 1. Code review editor (standalone Vite build)
bun run build:hook      # 2. Plan review + hook server (copies review's built HTML into hook dist)
bun run build:opencode  # 3. OpenCode plugin (copies built HTML from hook + review)
bun run build:pi        # 4. Pi extension (chains review → hook → pi internally, safe to run after 1-2)

build:pi は review と hook を内部で連続実行するため、手順 1～2 の後は Pi 固有のビルドのみが実行されます。

続行する前に、すべてのビルドが成功することを確認してください。

Pi パリティゲート

ビルドが成功したら、Pi 拡張機能を監査して、サーバー側のすべてのインポートが公開パッケージ内で解決されることを確認します。これにより、npm に公開される前にファイルの不足を検出できます。

  1. インポートと files 配列を照合します。 index.ts、server.ts、tool-scope.ts、および server/ 内のすべてのファイルから、ローカルインポート（./ または ../ で始まるもの）をたどります。各対象が apps/pi-extension/package.json の files 配列内のパターンで含まれていることを確認します。

  2. vendor.sh がすべての shared/ai インポートに対応していることを確認します。 サーバーファイル内のすべての ../generated/*.js インポートに、vendor.sh のコピー処理ループ内の対応するエントリーが必要です。packages/shared/ または packages/ai/ に新しい shared モジュールまたは AI モジュールが追加され、Pi のサーバーコードからインポートされている場合は、vendor.sh に追加する必要があります。

  3. パックをドライランします。 cd apps/pi-extension && bun pm pack --dry-run を実行し、出力にサーバーがインポートするすべてのファイルが含まれていることを確認します。特に、前回のリリース以降に追加されたファイルがないか確認してください。

  4. 簡易スモークテストを実行します。 ビルド後に generated/ に必要なファイルがすべて含まれていることを確認します。特に、新しいファイル（例：今回のリリースサイクルで追加された shared モジュール）を確認してください。

不足がある場合は、フェーズ 4 に進む前に修正します。よくある修正方法は次のとおりです。

  • ファイルを vendor.sh のコピー処理ループに追加する
  • ファイルまたはディレクトリを package.json の files 配列に追加する
  • インポートパスを修正する（Pi では @plannotator/shared や @plannotator/ai ではなく ../generated/ を使用します）

フェーズ 4：コミット、タグ付け、リリース

  1. バージョン更新をコミットします：

    chore: bump version to X.Y.Z

    バージョンを更新した 7 ファイルのみをステージングします。リリースノートファイルは意図的に未追跡のままにしておき、ステージングしないでください。

  2. タグを作成してプッシュします：

    git tag vX.Y.Z
git push origin main
git push origin vX.Y.Z

    v* タグのプッシュによって、リリースパイプライン（.github/workflows/release.yml）が起動します。

  3. パイプラインが残りのすべてを処理します：

    • テストを実行します
    • 6 つのプラットフォーム（macOS ARM64/x64、Linux x64/ARM64、Windows x64/ARM64）向けにバイナリをクロスコンパイルします
    • ペーストサービスのバイナリをコンパイルします（同じ 6 つのプラットフォーム）
    • 認証情報を使用しないジョブで 2 つの npm パッケージをパッケージ化します
    • 固定バージョンでチェックサム検証済みの Syft と Grype のバイナリをダウンロードし、出荷対象がすべて揃った後に、リリース全体を対象とする CycloneDX SBOM を生成してスキーマ検証します
    • リポジトリで管理する抑制なしの Grype 設定を強制し、公式データベースの更新を最大 3 回まで再試行します。さらに、120 時間以内に更新された有効かつアクティブな v6 スキーマのデータベースがあり、保留中の更新がないことを必須とし、機械可読なスキャン／データベース／ポリシーの証跡をワークフローのアーティファクトとして保持します
    • スキャナー側で無視された検出結果をすべて拒否し、CISA KEV に該当するもの、または出荷対象／実行時と分類された修正可能な Critical 脆弱性、および適用可否が不明な修正可能な Critical 脆弱性があれば、アテステーションや公開の前に処理を停止します。High、開発専用、および修正方法がない Critical の検出結果はレポートのみを対象としますが、証跡には引き続き含めます
    • actions/attest-build-provenance を通じて、12 個すべてのバイナリに対する SLSA ビルド来歴のアテステーションを生成します（Sigstore で署名され、Rekor に記録されます）
    • 独立した公式の actions/attest SBOM 経路を使用し、同じ GitHub OIDC/Sigstore サービスを通じて、CycloneDX predicate を 12 個すべてのバイナリと 2 つの npm tarball に紐付けます。これはインベントリアテステーションであり、SLSA や npm の来歴に代わるものではありません
    • すべてのバイナリ、SHA256 サイドカー、バージョン付き CycloneDX SBOM、およびその SHA256 サイドカーを添付して GitHub Release を作成します
    • 来歴付きで @plannotator/opencode と @plannotator/pi-extension を npm に公開します

    SBOM の対象範囲： 公開ドキュメントは、モノレポのロックされたビルド入力と依存関係を対象とする、リリース全体の Syft インベントリです。実際のバイナリの実行時コンテンツを正確に表すものとは意図的に説明していません。対象範囲のテストでは、Bun のスタンドアロン実行ファイルからは、バンドルされた JavaScript 依存関係のメタデータを Syft が検出できないことが分かりました。OpenCode の tarball も同様に内容を読み取れません。Pi の tarball から確認できるのは、入れ子になった package-lock ファイルを通じた部分的な情報のみです。対象範囲と制限事項は CycloneDX メタデータにも埋め込まれています。

    例外： 現在、有効な本番環境向け例外ファイルはありません。将来のリリース基準で例外が必要になった場合も、単純な ignore を追加しないでください。リポジトリでレビュー済みの OpenVEX ドキュメントを追加し、PLANNOTATOR_RELEASE_VEX を通じて明示的に指定してください。各ステートメントは、1 つの正確なパッケージ URL と脆弱性 ID に一致し、not_affected ステータス、OpenVEX の根拠、影響の説明、HTTPS の証拠、所有者、作成日、および有効期限を含める必要があります。ポリシーテストでは、期限切れ、不正な形式、対象範囲が広すぎる、または一致しないレコードを拒否します。

    不変リリースに関する注意： リポジトリでは GitHub Immutable Releases が有効になっているため、v* タグをプッシュしてリリースを作成すると、タグからコミットへの紐付けとタグからアセットへの紐付けは恒久的なものになります。不正なリリースを「修正」するためにタグを削除して作り直すことはできません。新しいバージョンをリリースする必要があります。リリースノートは引き続き編集できます（ステップ 5 を参照）が、それ以外はすべてロックされます。

  4. パイプラインを監視します： リリースワークフローの実行が完了するまで確認します：

    gh run list --workflow=release.yml --limit=1
gh run view <run-id> --log

    次の点を確認します：

    • release-security、attest、release、npm-publish を含むすべてのジョブが成功している
    • release-security-evidence に Syft／Grype のバージョン、アクティブなデータベースのスキーマ／ビルド／チェックサム／更新ステータス、Grype のすべての検出結果、および ACCEPT のポリシー判定が記録されている
    • すべてのバイナリアーティファクト、SHA256 サイドカー、バージョン付きの plannotator-X.Y.Z-release-sbom.cdx.json、およびその .sha256 サイドカーを含む GitHub Release が作成されている
    • npm パッケージの公開が成功している（npm view @plannotator/opencode version と npm view @plannotator/pi-extension version で確認します） プルリクエストは、生成、スキーマ/センチネル検証、データベースポリシー、Grype 評価、最小権限のジョブ配線、およびすべてのレポート成果物を証明します。GitHub OIDC の発行、アーティファクト証明サービスへの公開、および最終的なリリースアセットの公開は、実際に適格な v* タグに対してのみ実行されます。この制御が導入された後の最初のリリースでは、ロールアウト完了と見なす前に、この範囲を限定したタグのみの検証を完了してください:

    その最初のリリースにタグを付ける前に、https://docs.plannotator.ai/open-source/start/installation#pin-or-verify-a-release にある正規の Mintlify ページを、SBOM のスコープ/制限事項、Grype ポリシー、ダウンロード/チェックサムコマンド、および README にある両方の述語検証コマンドで更新してください。apps/marketing/src/content/docs/ 配下のレガシーな Astro ファイルはリダイレクト専用/非推奨のコピーであり、公開ドキュメントのソースではありません。ライブの Mintlify ページにその内容が含まれていることを確認してください。その公開が出荷済みの制御より遅れないようにしてください。

    tag=vX.Y.Z
version="${tag#v}"
gh release download "$tag" --pattern 'plannotator-linux-x64*' --pattern "plannotator-${version}-release-sbom.cdx.json*" --dir /tmp/plannotator-release-verify
(cd /tmp/plannotator-release-verify && sha256sum --check plannotator-linux-x64.sha256)
(cd /tmp/plannotator-release-verify && sha256sum --check "plannotator-${version}-release-sbom.cdx.json.sha256")

gh attestation verify /tmp/plannotator-release-verify/plannotator-linux-x64 \
  --repo backnotprop/plannotator \
  --source-ref "refs/tags/$tag" \
  --signer-workflow backnotprop/plannotator/.github/workflows/release.yml \
  --predicate-type https://slsa.dev/provenance/v1

gh attestation verify /tmp/plannotator-release-verify/plannotator-linux-x64 \
  --repo backnotprop/plannotator \
  --source-ref "refs/tags/$tag" \
  --signer-workflow backnotprop/plannotator/.github/workflows/release.yml \
  --predicate-type https://cyclonedx.org/bom

    また、gh attestation verify --format json --jq '.[0].verificationResult.statement.predicate' で証明済みの CycloneDX 述語を抽出し、それとダウンロードしたリリース SBOM の両方を jq -S で正規化し、cmp で比較してください。正確に公開された tarball をダウンロードした場合は、1 つの npm tarball サブジェクトも同じ方法で検証してください。タグのみに関連する不一致はリリースブロッカーとして記録し、イミュータブルなリリースを変更するのではなく、新しいバージョンを出荷してください。

    何かが失敗した場合は、ログを調査し、再試行する前にユーザーに報告してください。

  5. リリースノートを置き換える: リリースが公開され検証されたら、自動生成されたノート本文を下書きしたリリースノートで置き換えます:

    gh release edit vX.Y.Z --notes-file RELEASE_NOTES_v<VERSION>.md

チェックリスト

タグを付ける前に、次を確認してください:

  • 7 つのバージョンファイルすべてが一貫してバンプされている
  • リリースノートが下書きされ、レビュー済みである
  • bun run build:review が成功した
  • bun run build:hook が成功した
  • bun run build:opencode が成功した
  • bun run build:pi が成功した（または pi 固有のビルドステップ）
  • バージョンバンプがコミットされている
  • Pi パリティゲートが通過した（imports、vendor.sh、dry-run pack）
  • 古いビルド成果物がない（クリーンビルド、キャッシュ問題なし — 依存関係が変更された場合は最初に bun install を実行）
  • PR セーフな release-security ジョブが、スキーマに準拠しセンチネルが完全な SBOM を生成し、新しいデータベースで Grype ポリシーを承認した
  • スキャナーバイナリ、データベース、生成された SBOM/レポート、認証情報、または DO_NOT_COMMIT の内容がステージングされていない
  • SBOM が有効な最初のリリースでは、正規の Mintlify インストール/検証ページに README の SBOM スコープ、ポリシー、チェックサム、SLSA、および CycloneDX コマンドが含まれている（代わりに非推奨の Astro ドキュメントを編集しないこと）

タグを付けた後に、次を確認してください:

  • リリースワークフローが release-security、attest、release、npm-publish のすべてグリーンで完了した
  • GitHub Release がすべてのバイナリ、サイドカー、SBOM、および SBOM サイドカー付きで作成された
  • 1 つのネイティブバイナリが、タグと署名者ワークフローに固定された明示的な SLSA および CycloneDX 述語チェックの両方に合格する
  • ダウンロードした SBOM のチェックサムが合格し、正規化された JSON が証明済みの述語と一致する
  • release-security-evidence が新しい/アクティブなデータベースと承認されたポリシー決定を示している
  • npm パッケージが正しいバージョンで公開されている
  • npm のトラステッドパブリッシング来歴が両方のパッケージで引き続き表示されている
  • リリースノートが gh release edit で置き換えられている

コメント

Markdown 対応