update-release-notes

リリースノートの更新

このスキルは、tldraw/tldraw リポジトリでリリースノートを維持するための運用タスクを処理します。next.mdx に新しい PR エントリを追加し、新しいバージョンが公開されたときにリリースをアーカイブします。

このスキルは tldraw-internal リポジトリから実行されますが、tldraw/tldraw のローカルクローンに対して操作を行います。

セットアップ

開始する前に、tldraw リポジトリをクローンします:

git clone https://github.com/tldraw/tldraw.git /tmp/tldraw

すべてのスクリプトは、リポジトリのパスを最初の引数として受け取ります。この SKILL.md を含むディレクトリを <skill-dir> に置き換えて、リポジトリのルートからスクリプトコマンドを実行します。すべてのファイル編集はこのクローン内で行われます。最後に、クローンからコミットしてプッシュします。

リリースサイクル

SDK は 4 週間ごとにリリースされます。ローンチの 1 週間前に SDK はフリーズされ、main から production ブランチが切られます。リリース週の間は、ホットフィックスのみが production にチェリーピックされます。

next.mdx のリリースノートは、最終的に production ブランチで出荷される内容を反映している必要があります。ただし、フリーズ前の約 3 週間の開発期間中は、リリースノートが空にならないように main からリリースノートを積み上げていきます。ステータススクリプトは、最後のマイナーリリースの日付に基づいて、どのフェーズにいるかを検出します:

• 開発週 (source: "main"、最後のマイナーリリースから 3 週間未満): PR は最後のリリースタグ以降の main から収集されます。これらは暫定的なものであり、リバートされたり、production のチェリーピックが異なったりすると、出荷されないものもあります。
• フリーズ週 (source: "production"、最後のマイナーリリースから 3 週間以上): PR は、前回のリリースブランチに対して git cherry を使用して production ブランチから収集されます。フリーズ前にランディングした PR、または production にホットフィックスされた PR のみが含まれます。main から蓄積されたエントリのうち、production にないものは削除されます。

next.mdx 自体も、リリースが公開される前に production 上にある 必要があり、単にそれを記述するだけではいけません。prepack.ts は、公開されるチェックアウトから tldraw npm パッケージ内に同梱される RELEASE_NOTES.md を生成し、リリースされるバージョンのエントリとして next.mdx を使用します。production はフリーズ中はホットフィックスによってのみ移動するため、main にマージされたリリースノートの PR は、dotcom-hotfix-please ラベルも付けられている場合にのみそこに到達します (ステップ 10 を参照)。公開前のチェックは、空の差分です:

git diff --stat origin/production origin/main -- apps/docs/content/releases/next.mdx

プロセス

1. ステータスを確認する

ステータススクリプトを実行して、バージョンと diff ブランチを判定します:

<skill-dir>/scripts/get-changelog-status.sh /tmp/tldraw

これは次を返します:

• source - "main" (開発週) または "production" (リリース週) のいずれか
• diff_branch (例: v4.3.x) - diff の対象となるブランチ (source が "production" の場合に使用)
• last_tag (例: v4.4.0) - 最後のリリースタグ (source が "main" の場合に使用)
• latest_release - 最も最近公開されたリリース
• アーカイブが必要かどうか

2. アーカイブを処理する (必要な場合)

next.mdx の last_version 以降に新しいリリースが公開された場合:

1. next.mdx の内容を vX.Y.0.mdx (例: v4.3.0.mdx) にコピーします
2. 新しいファイルのフロントマターを更新します:
   • title をバージョンに設定します
   • 日付を更新します
   • フロントマターの後に GitHub リリースへのリンクを追加します
3. apps/docs/content/getting-started/releases.mdx のリリースインデックスに新しいバージョンを追加します:
   • 該当する ## v{major}.x セクションの先頭に行を追加します
   • 形式: - [vX.Y](/releases/vX.Y.0) - Brief description
   • 説明は、導入段落からのリリースハイライトの短い要約である必要があります (3〜5 個の主要機能をカンマ区切りで)
   • 新しいメジャーバージョンのセクションが必要な場合は、前のセクションの上に作成します
4. next.mdx をリセットします:
   • last_version フィールドを新しいリリースに更新します
   • コンテンツセクションをクリアします
   • 新しい変更を蓄積するためにファイル構造を維持します

3. 新しい PR を見つける

アプローチは、ステップ 1 の source フィールドによって異なります。

source が "production" の場合(リリース週):

前回のリリース以降の本番ブランチ上の PR 番号を取得します:

<skill-dir>/scripts/get-new-prs.sh /tmp/tldraw <diff_branch>

これは git cherry(extract-draft-changelog.tsx と同じアプローチ)を使用して、origin/production と origin/<diff_branch> の間のパッチを比較します。git log とは異なり、git cherry はコミットハッシュではなくパッチの内容を比較することで、チェリーピックされたホットフィックスコミットを正しく処理します。

source が "main" の場合(開発週):

最後のリリースタグ以降の main 上の PR 番号を取得します:

<skill-dir>/scripts/get-new-prs-from-main.sh /tmp/tldraw <last_tag>

これは git cherry を使用して、origin/main とリリースタグの間のパッチを比較し、production にチェリーピックされてすでにリリースで出荷されたコミットを除外します。

両方のスクリプトの出力:

• stdout: コミットメッセージから抽出された PR 番号(1 行に 1 つ)
• stderr: PR 番号のないコミット(通常はホットフィックスまたは直接コミット)

4. ホットフィックスコミットを解決する

ステップ 3 の stderr で、PR 番号のない [HOTFIX] コミットがないか確認します。SDK に関連するものごとに(dotcom のみのものはスキップ)、対応する PR を見つけます:

gh pr list -R tldraw/tldraw --state merged --search "<hotfix title keywords>" --json number,title --jq '.[]'

また、sdk-hotfix-please ラベルが付いた PR も確認しますが、それらが実際に production に反映されたことを検証してください。このラベルは前回のリリースブランチ(例: v4.3.x)のパッチリリースにも使用されます:

gh pr list -R tldraw/tldraw --label "sdk-hotfix-please" --state merged --limit 20 --json number,title,mergedAt

一致した PR 番号があれば、ステップ 3 の production PR リストに追加します。

5. PR の詳細を取得する

すべての PR 情報を一括取得します:

<skill-dir>/scripts/fetch-pr-batch.sh <pr1> <pr2> ...

6. 古いエントリを削除する

完全な PR リスト(ステップ 3 + 4 から)を、next.mdx ですでに参照されている PR 番号と比較します。next.mdx から、PR が現在のセットに含まれていないエントリを削除します。

• source が "production" の場合: これは、開発中に main から蓄積されたものの、production に反映されなかったエントリを削除します。これらは、production ブランチが切られた後に main に反映された PR であり、今回のリリースでは出荷されません。
• source が "main" の場合: これは、リバートされた、またはその他の理由で main 上にもはや存在しない PR のエントリを削除します。production が切られるまで完全なセットが確定しないため、削除はそれほど積極的ではありません。

エントリを削除するときは、それが特集の「What's new」セクションで参照されていないかも確認し、そのセクションも削除します。削除された機能について言及している場合は、イントロ段落も更新します。

7. 新しいエントリを追加する

next.mdx にまだ含まれていない各 PR について:

1. PR のラベルと本文をスタイルガイドの分類ルールと照らし合わせて確認する
2. 省略すべき PR をスキップする(スタイルガイドを参照)
3. 同じリリースサイクルで導入されたバグを修正する PR をスキップする(つまり、前回のリリースには含まれていなかった、next.mdx にすでにある他の PR によって引き起こされたバグ)
4. PR がリバートである場合、元のリバートされた PR のエントリが next.mdx にあればそれも削除する
5. 適切なセクションにエントリを追加する
6. 必要に応じて、重要な変更を特集セクションに昇格させる

8. 検証

以下を確認します:

• next.mdx で参照されているすべての PR が、現在の PR セット(source に応じて main または production から)に含まれている
• PR リンクが正しい
• コミュニティのコントリビューターがクレジットされている
• セクションが正しい順序になっている
• 破壊的変更が 💥 でマークされている
• 非推奨が 🔜 でマークされている

注: source が "main" の場合、エントリは暫定的なものです。production ブランチが切られて source が "production" に切り替わると、一部は後で削除される可能性があります。

9. ドラフトの GitHub リリースを更新する

次のマイナーリリース用のドラフト GitHub リリースを next.mdx と同期させておきます。publish-new.ts はドラフトを名前（vX.Y.0）で検索し、リリース時にその本文をそのまま公開するため、ここで next.mdx を反映しておけば、GitHub リリースとドキュメントのリリースページは常に一致します。

<skill-dir>/scripts/update-draft-release.sh /tmp/tldraw

このスクリプトは次のことを行います。

• next.mdx の last_version から対象バージョンを導出します（マイナーをバンプし、パッチを 0 にします — 例: v5.2.0 → v5.3.0）。
• next.mdx の本文（frontmatter を除去したもの）をリリース本文として使用します。
• ドラフトが存在しない場合は作成し、vX.Y.0 という名前の既存のドラフトがある場合は編集します。すでに公開済みのリリースには手を付けず、空の本文も書き込みません。

メジャーリリース / バージョンの上書き: 上記のマイナーバンプがデフォルトである理由は、ほぼすべてのリリースがマイナーだからです。publish-new.ts は、自身が解決したバージョンでドラフトを検索します — --bump major（または上書き）の場合、そのバージョンはマイナーバンプではなく NPM から取得されるため、マイナーをハードコードしているとドラフトの名前が一致せず、getDraftRelease が失敗します。次のリリースがメジャーである場合、または次のマイナーでない場合は、ドラフト名が一致するように対象を明示的に指定してください。

<skill-dir>/scripts/update-draft-release.sh /tmp/tldraw v6.0.0

next.mdx を更新するたびに、リリース週の実行も含めてこれを実行してください。2 回目（公開後）の実行では、前のマイナーのドラフトはすでに公開されているため、リセットされた last_version から導出された新しい次のマイナー用のドラフトが新規に作成されます。

10. 変更をプッシュする

next.mdx (および任意のアーカイブファイル) を編集したら、tldraw のクローンからコミットしてプッシュします。ブランチのコミットに [skip ci] を追加しないでください。このマーカーが存在すると、必須のプルリクエストチェックが開始されなくなります。以下の PR タイトルは、代わりに最終的なスクアッシュマージコミットにマーカーを追加します。

cd /tmp/tldraw
BRANCH="update-release-notes-$(date -u +%Y%m%d-%H%M)"
git checkout -b "$BRANCH"
git add apps/docs/content/releases/
git commit -m "docs(releases): update release notes"
git push -u origin "$BRANCH"

次に、../pr/SKILL.md のワークフローと ../write-pr/SKILL.md の標準に従って PR を作成します。

• ラベル: docs-hotfix-please を追加します (gh pr edit <number> --add-label docs-hotfix-please、または gh pr create で --label docs-hotfix-please)。これがないと、main へのマージでリリースノートが現在のリリースブランチ (vX.Y.x) にチェリーピックされず、更新が tldraw.dev に到達しません。これはこの実行の本来の目的です。
• フリーズ週ラベル: source が "production" の場合、dotcom-hotfix-please も追加します。これにより、マージされた PR が hotfixes にチェリーピックされ、そこから production に反映されます。リリース公開時に prepack.ts が next.mdx を読み取るのはこの production です (「リリースサイクル」を参照)。docs-hotfix-please だけでは production には一切触れません。マージ後、「リリースサイクル」の diff コマンドでホットフィックスが反映されたことを確認します。dotcom ホットフィックスボットが失敗した場合は、hotfixes からブランチを作成してスクアッシュコミットを手動でチェリーピックし、コミットメッセージから [skip ci] マーカーを削除して、hotfixes に対して [HOTFIX] PR を作成します。
• タイトル: docs(releases): update release notes [skip ci] — [skip ci] は PR タイトルに含める必要があります。GitHub のスクアッシュマージは PR タイトルをマージコミットのサブジェクトとして使用し、CI をスキップする必要があるのはこのマージコミットだからです。PR を スクアッシュマージ します (リベースやマージコミットの作成は行わないでください)。これにより、ベースブランチに [skip ci] コミットがちょうど 1 つだけ着地します。
• 変更タイプ: other
• テストプラン: 番号付きリストを削除します (手動テスト手順はありません)。単体テストとエンドツーエンドテストの両方のチェックを外します。
• リリースノート: このセクションは省略します (ユーザーに影響しない内部ドキュメント作業)
• 説明の段落: 「In order to...」で始め、source (main または production) と、何が更新されたか (新しいエントリの追加、古いエントリの削除、アーカイブの実行、GitHub ドラフトリリースの同期など) に言及します。
• Documentation 行を含む コード変更 テーブルを含めます

[skip ci] が PR タイトルにのみ含まれる理由: ブランチのコミットでは、必須のプルリクエストチェックを実行する必要があります。GitHub のスクアッシュマージはマージコミットに PR タイトルを使用するため、リリースノートのみの変更が main に着地したときに、このマーカーがプッシュワークフローをスキップします。

[skip ci] は docs-hotfix-please ラベルを妨げません。trigger-sdk-hotfix.yml は pull_request_target で実行され、GitHub の skip-ci マーカーはこれに影響しません。また、ホットフィックススクリプトはチェリーピックしたコミットから skip-ci マーカーを削除するため、リリースブランチへのプッシュでもパブリッシュワークフローがトリガーされます。このトリガーはラベル付きの PR がマージされたときに発生します。後で再トリガーするには、マージされた PR でラベルを削除して再度追加します。dotcom-hotfix-please についても、#10629 が修正されれば同じことが当てはまります。それまでは、そのボットはマーカーを保持し、開かれるホットフィックス PR のチェックが実行されません。

PR 本文の他の場所に [skip ci] という文字列をそのまま書かないでください。GitHub はスクアッシュマージコミットメッセージ全体からマーカーを読み取り、PR 本文はそのコミットの本文になります。

last_version フィールド

next.mdx のフロントマターには、直近に公開されたリリースを追跡する last_version フィールドが含まれています。これはどの PR が「新規」で追加が必要かを判断します。

SDK リリースワークフロー

SDK リリース時には、ドキュメントサイトをリリース後の状態にするために、このスキルが 2 回 実行されます。

1. 1 回目の実行 — リリースで出荷されるすべての PR を next.mdx に反映します（フリーズ週のソースは "production"）。これにより、公開前にリリースノートが完全な状態になります。ドラフトリリースのステップ（ステップ 9）は、この next.mdx からドラフトの vX.Y.0 GitHub リリースを同期するため、publish-new.ts は完成したノートを公開できる状態で保持します。PR は docs-hotfix-please と dotcom-hotfix-please の両方（ステップ 10）を持つため、ファイルはサイト用の v(X.Y-1).x とパッケージ用の production に届きます。
2. ゲート — 誰かが公開する前に、next.mdx は production と main で同一でなければならず（「リリースサイクル」の diff コマンドが何も出力しないこと）、ドラフトの vX.Y.0 リリースは next.mdx と一致している必要があります。その後 next.mdx への編集が dotcom ホットフィックスなしで main に入った場合、または最後のドラフト同期の後に入った場合は、まずそれを修正してください。
3. リリースを NPM に公開 — これはこのスキルの範囲外で行われます。publish-new.ts はステップ 1 で作成されたドラフトリリースを公開し、prepack.ts は production の next.mdx をそのバージョンの RELEASE_NOTES.md エントリとして tldraw パッケージに焼き込みます。公開はバージョンバンプを production ではなく main にプッシュします。
4. 2 回目の実行 — リリースが公開されたので、ステータススクリプトは needs_archive: true を検出します。このワークフローは production へのプッシュで実行されますが、公開はプッシュを行わないため、2 回目の実行は次の production プッシュ時（通常は main からのローンチ後の dotcom リリース）、または誰かが update-release-notes.yml を手動でディスパッチしたときに発生します。この実行では:
   • next.mdx をバージョン付きファイル（例: v4.5.0.mdx）にアーカイブします
   • 新しいバージョンをリリースインデックス（releases.mdx）に追加します
   • 新しい last_version で next.mdx をリセットします
   • フリーズ中（リリースタグ以降）に main に入った PR を検出し、新しい next.mdx に追加します
   • 前回のドラフトが公開されたため、新しい次のマイナーバージョン用の新しいドラフトを同期します（ステップ 9）
   • 新しい vX.Y.x ブランチに入りサイトを再公開するために、docs-hotfix-please（dotcom-hotfix-please ではない: パッケージが出た後はノートに production はもう関係ありません）が必要です

2 回目の実行後、ドキュメントサイトには公開されたリリースが反映され、next.mdx には次のサイクルの変更に対する先行スタートがすでにあります。

参考資料

• スタイルガイド: リリースノートの記事に何を含めるべきか、どのようにフォーマットするかについては ../shared/release-notes-guide.md を参照してください。
• 執筆ガイド: ボイスとスタイルの規約については ../../VOICE.md を参照してください。
• スクリプト: ドラフト GitHub リリースを同期するための update-draft-release.sh を含む自動化ヘルパーについては scripts/ を参照してください