openseo-release-notes

OpenSEO リリースノート

このリポジトリのリリースを最初から最後まで作成します。成果物は、package.json のバージョン更新、新しい docs/release-notes/v<version>.md、および release: v<version> というタイトルで origin/main に対して作成する PR です。

1. バージョンを更新する

• package.json を読みます。ブランチですでに version が更新されている場合は、それを正として扱い、変更しないでください。
• そうでなければ、パッチバージョンを上げます（例：0.0.19 → 0.0.20）。明示的に指示された場合を除き、マイナー／メジャーバージョンは上げないでください。

2. 前回のリリース以降の変更を集める

• 最新のタグを確認します：git tag --sort=-creatordate | head -1。ブランチが origin/main と同期していることを確認します（git fetch origin main && git log HEAD..origin/main --oneline の結果が空である必要があります。空でなければ報告してください）。
• コミットを一覧表示します：git log <last-tag>..HEAD --oneline。コミットの一覧を確認するために pnpm release:notes を実行してもかまいません。ただし、候補となる変更のチェックリストとしてのみ使用し、ドラフトの構成には使用しないでください（その Improved／Changed／Docs セクションをノートに含めないでください）。
• 各コミットについて、PR の本文と作成者を取得します（gh pr view <num> --repo <repo> --json title,body,author）。スクワッシュコミットの件名は古い可能性があります。コミット件名の (#NN) は、どちらのリポジトリも参照する可能性があります。まず bensenescu/open-seo（origin）を試し、見つからない場合は every-app/open-seo（public）を試してください。外部コントリビューターの PR と GitHub ハンドルは public リポジトリにあります。(#NN) のないコミットでも、public リポジトリに外部コントリビューターの PR が存在する場合があります（gh pr list --repo every-app/open-seo --state merged --author <login>）。作成者を確認するには git log --format=%an を確認してください。PR の本文とコミット件名が食い違う場合は、最終的なコードに照らして内容を確認してください（機能がマージ前に取り消されることがあります）。
• 各変更について、箇条書きでクレジットを記載できるよう、PR 作成者の GitHub ハンドルも記録します。

3. リリースノートを作成する

docs/release-notes/v<version>.md を作成します。docs/release-notes/v0.0.24.md が標準スタイルの見本です。これに合わせてください（v0.0.25 以降も同じスタイルです）。v0.0.23 以前は古い冗長なスタイルなので、決してまねしないでください。リリースノートは一覧性の高い概要であり、ドキュメントではありません。ファイル全体を1画面に収め（見出しを含めて約15行）、すべての行に意味を持たせてください。

形式：

• 最初の行：リリースの主な見どころを2～3個挙げた断片的な文にします（「GSC UI、アプリレイアウトの改善、アプリ内エージェントのベータ版」など）。「今回のリリースでは……」のような文章にはしません。
• セクションは ## What's new と ## Fixed のみです。「Improved」セクションはありません。改善点は「What's new」に載せるほど目玉になるものか、掲載しないかのどちらかです。
• 「What's new」の箇条書きでは、機能名を示し、売り込みはしません。 短い1行にします（「アプリレイアウトを刷新」「アプリ内で GSC Insights を利用可能に」など）。機能を長々と説明するダッシュ付きの文や、「〜できるようになります」といったメリットの説明、機能が影響する対象をすべて並べる記述は避けてください。機能名だけでは意味がわかりにくい場合に限り、平易な言葉で1節だけ補足できます。
• 機能ごとのサブ項目は最大1つで、短い1行にします。最も役立つ詳細、要件（OPENROUTER_API_KEY が必要）、または事前に伝えておくべき事項を1つだけ記載します。
• 完成度の低い機能には「(Beta)」を付けてください。 期待値を正直に伝え、現時点でより適切な代替手段がある場合は示してください。期待値の説明はトップレベルの行にダッシュで続けて記載します（「(Beta) アプリ内エージェント — 現時点では MCP の利用をおすすめしますが、夏の間に改善を進める予定です。」）。これにより、サブ項目には要件や詳細を記載できます。
• 「Fixed」には、ユーザーが実際に遭遇し、問題だと認識しそうな不具合だけを、平易な文で3～5個記載します（「AI 検索で Claude が再び回答するようになりました。」など）。エラーコード、ステータスコード、スキーマやインフラの用語、仕組みの説明は含めません。該当する不具合が4個を超える場合は、主要なフロー（検索、監査、トラッキング、MCP の回答）に関わるものを優先し、ユーザー自身が起こした状態を復旧するための修正（再追加、アーカイブ解除、更新など）から先に除外してください。
• コントリビューターに謝意を示してください。 外部コントリビューターの場合に限り、箇条書きの末尾に — thanks @handle を付けます。メンテナー自身の PR（bensenescu）には付けません。謝意はサブ項目ではなく、トップレベルの箇条書きに記載します。複数人の場合は — thanks @a, @b とします。
• 最後に次の行を記載します：Full Changelog: https://github.com/every-app/open-seo/compare/v<prev>...v<version>

取捨選択 — ここが最も重要です。細かい変更は Full Changelog リンクで確認できるため、思い切って削ってください。

• 製品そのものの変更だけを取り上げます。アプリ、MCP ツール、OpenSEO を実行するユーザーが実際に使う SEO データや機能が対象です。箇条書きごとに次の基準で判断してください。セルフホストするユーザーが、製品を使っていてこの変更に気づくか。 新しいバックエンドの選択肢や上限の引き上げなど、抽象的な関心だけでは不十分です。
• 以下は記載しないでください。
  • マーケティングサイト（web/）の変更 — ランディングページ、文言、ポジショニング、ブログ。
  • 料金、プラン、サブスクリプション、請求 — ペイウォール、無料トライアルやプランの変更、Autumn の設定。ホスト型商用サービスに関するもので、セルフホストするユーザーには関係ありません。
  • オンボーディングフローだけの変更 — サインアップやオンボーディング時のチャット、プロファイリングの手順、アップグレード案内、メール認証の UX。大規模な変更であっても、製品の機能ではありません。
  • ホスト型アプリの内部実装や関連情報 — アナリティクス、仕様書／ADR、CI、リファクタリング、依存関係の更新。
  • 製品に関係していても、ユーザーから見えない作業 — セキュリティ強化、上限の引き上げ、安定性・メモリ・パフォーマンスの修正、データベースやバックエンドの選択肢、移行。リリースノートを読むユーザーが、製品を使った経験から各行の内容を認識できる必要があります。設定ファイルを見たり、起きなくなった障害に遭遇したりしないと気づけない変更は除外してください。
• 掲載するか迷ったら、掲載しないでください。読まれる「What's new」の箇条書き4個は、読まれない10個より優れています。
• 機能をでっち上げないでください。すべての記述はコミットに根拠をたどれる必要があります。
• 箇条書きに数字を入れると、たいてい売り込みに見えます。数字は省いてください。本当に不可欠な数字であれば、都合のよい最高値ではなく、控えめで一般的な数値を使います。

4. レビューと検証

1. 草案、上記のガイドライン、収集したコミットごとの事実、リポジトリへのアクセス権をレビュー担当のサブエージェントに渡して起動します。ガイドラインのどれに違反しているかを示した、番号付きのレビューコメントが返されます。担当範囲には冗長さも含まれます。名前を挙げるのではなく売り込む箇条書き、2つ目のサブ箇条書き、仕組みに関する語彙を含む Fixed の箇条書き、ファイルが1画面を超える原因となる記述を指摘します。
2. 実質的なコメントごとに、検証担当のサブエージェントを並列で起動し、実際のコミットやコードと照らし合わせてコメントを批判的に確認し、APPLY／APPLY-MODIFIED／REJECT の判定を行わせます。
3. 検証済みのコメントのみを反映します。

5. PR を作成する

• バージョンの更新、リリースノート、スキルの変更を、claude/v<version> という名前のブランチにコミットします（現在のブランチがすでにこのパターンに従っている場合は、そのブランチを使用します）。

• origin にプッシュし、タイトルを正確に release: v<version> として、main に対する PR を作成します。PR の本文にはリリースノートの内容を記載します。

• タグ付けや GitHub リリースの公開は行わないでください。これらはマージ後に行われます。マージ後、pnpm release:publish を実行します。これは package.json からバージョンを読み取り、対応する docs/release-notes/v<version>.md を every-app/open-seo に公開します。

• 同等のコマンドは次のとおりです。

  gh release create v<version> \
    --repo every-app/open-seo \
    --title v<version> \
    --notes-file docs/release-notes/v<version>.md