assemble-changelog

Assemble-changelog

Rerun リポジトリのリリース時に変更履歴を組み立てます。

必ず、独立した rerun-io/rerun チェックアウトのルートで作業してください。通常は、結果をコミットする prepare-release-0.x.y ブランチです。 これは RELEASES.md の手順 4 です。周辺のコンテキストを確認するため、こちらを読んでください。

リリース作業を始める前に、現在のディレクトリがリポジトリのルートであり、origin が rerun-io/rerun であることを確認してください。

test "$(git rev-parse --show-toplevel)" = "$PWD"
git remote get-url origin

reality モノレポでは、rerun/ ディレクトリからの場合も含め、このワークフローを実行しないでください。 リリーススクリプトでは、独立したリポジトリの 0.x.y タグが必要であり、(#N) のコミット参照は rerun-io/rerun に対して解決されます。 reality に対して実行すると、reality の PR 番号が無関係な Rerun の PR に誤って解決されても、気づかない可能性があります。

どちらかの前提条件を満たしていない場合は、リリースコマンドを実行する前に中止してください。 このスキルには独立した rerun-io/rerun チェックアウトのルートが必要であることをユーザーに伝え、そこで再開するよう依頼してください。 ユーザーに代わってリポジトリをクローンしたり、タグをフェッチしたり、ブランチを切り替えたりしないでください。

$ARGUMENTS から対象バージョンを解決してください（例：0.34.0）。指定がない場合は、 Cargo.toml（version = "0.x.y-…"）から読み取り、ユーザーに確認してください。

ワークフロー

1. upcoming/ をリリース変更セットにまとめる

選定済みのエントリーは、docs/content/changelog/upcoming/*.md に PR ごとに 1 ファイルずつ格納されています （_template.md は除外します）。各ファイルのフロントマターには type: highlight|misc|breaking|feature が指定されています。これらを docs/content/changelog/changeset-0-XX.md にまとめてください。そのファイルがまだ存在しない場合は、 docs/content/changelog/_template.md をもとに作成してください（title をバージョンに設定します。YAML で文字列として扱われるよう、title: "0.36" のように引用符で囲んでください。また order は前のリリースより 1 小さい値にします）。

• highlight → ## Highlights の下に、それぞれ 1 つずつ ### の小見出しを追加します。
• feature → ## New features の下に、それぞれ 1 つずつ ### の小見出しを追加します。
• misc → ## Other の下に、各エントリーを - のリスト項目として、ちょうど 1 つずつ追加します。エントリーの ### 見出しと本文を項目にまとめ、リンクはそのまま維持してください。リスト項目以外に見出しや散文を使用しないでください。
• breaking → ## Breaking changes の下に、それぞれ 1 つずつ ### の小見出しを追加します。該当するものがない場合は、None. と記載してください。

セクションはこの順序を維持し、エントリーがない場合は Highlights と Other を省略してください。 変更履歴はウェブサイトの一部であり、ユーザー向けのものです。そのため、新しい内容から始めてください。 詳細で開発者向けの破壊的変更の移行ガイドは最後に置き、ほとんどの読者が読み進める必要がないようにします。

リリースの種類に合わせて出力を調整してください。

• パッチリリース（0.x.Y、Y > 0）→ 通常はバグ修正のみです。Highlights と New features は省略します（通常、upcoming/ にエントリーはありません）。雑多なエントリーがある場合のみ Other を含め、破壊的変更がある場合のみ Breaking changes を含めます。
• マイナーリリース（0.X.0）→ 完全なテンプレートを使用します：ハイライト、新機能、その他の項目、破壊的変更。

各エントリーの文章と構成（移行ガイド、表、snippet: ディレクティブ、スクリーンショット、リンク）を維持してください。ただし、雑多なエントリーはそれぞれ 1 つのリスト項目にまとめます。 重複するエントリーを除き、破壊的変更は影響の大きい順に並べてください。 エントリーごとのフロントマターは削除してください。

エントリー内の相対ドキュメントリンクは、changelog/ からのパスとして記述されています（例： ../reference/migration/...）。統合後も正しいため、そのまま維持してください。

画像と動画は static.rerun.io に置く必要があります（scripts/upload_image.py でアップロードしてください）。GitHub の添付ファイルは使わないでください。非公開モノレポにアップロードされた添付ファイルは、ウェブサイトに表示できません。

Feature リードは PR ごとに ## Highlights のエントリーを記述するため、このセクション全体を読み、まとまりのない内容があれば自分で書き換えず、人間に指摘してください。

最後に、docs/content/changelog.md のフロントマターにある redirect: を changelog/changeset-0-XX に向けてください。CI の scripts/ci/check_changelog_redirect.py では、最新の変更セットがリダイレクト先であることが求められるため、この変更は新しい変更セットと同時に反映する必要があります。

2. リリースを阻む問題を解決する

upcoming/ 内のテンプレート以外のファイルがすべて changeset にマージされていることを確認し、結合した changeset を検索して未解決のプレースホルダーを探します。

rg -n 'TODO\([^)]+\)' docs/content/changelog/changeset-0-XX.md # NOLINT

該当するものは、次に進む前にすべて解決してください。 未解決の TODO(name) があると、リリースできません。

3. サマリーと詳細セクションを生成し、CHANGELOG.md に記載する

pixi run uvpy scripts/generate_changelog.py --version 0.x.y

PR のタイトルやラベルを編集して出力を改善したら、結果を CHANGELOG.md にコピーします （末尾の「Chronological changes」セクションは削除し、プレースホルダーの動画／ブログ記事 の行は、過去のリリースと同じように置き換えてください）。いくつかの項目を実際の PR と照合して確認します。 タイトルの汚染（古い無関係な PR、コアチームメンバーへの thanks @…）がある場合は、PR 番号の 参照に失敗しています。冒頭の警告を確認してください。 生成されたセクションを読み、貢献者の誤ったクレジット表記や誤字がないか確認します。 Rust クレートを公開せずにリリースする場合（publish-crates=false）、このバージョンが crates.io で公開されないことを CHANGELOG.md のセクションに記載してください。

これは手順 1 の後に行ってください。スクリプトは結合した changeset を読み取り、その文章をそのまま掲載するのではなく、 サマリー（セクション見出しと、ウェブサイト上の changeset へのリンク）を出力します。 そのため、CHANGELOG.md に changeset の内容が重複して記載されることはありません。changeset がない場合、 スクリプトは未解決のプレースホルダーを出力します。

4. CHANGELOG.md のセクションを整える

生成されたセクションは出発点です。読者が詳細を見つけやすいように、手作業で編集してください。

• 概要を影響の大きい順に並べます。 まず大きな新機能を置き、次にインテグレーションと API、続いてフォーマットのサポート、仕上げの改善、最後にニッチな項目や開発者向けの項目を置きます。

• 詳細を分類して並べます。 スクリプトは各詳細サブセクション（🐍 Python API、🪳 バグ修正、🌁 ビューアーの改善など）をコミット順に出力します。 各サブセクション内では、同じ機能に関する項目（たとえば、MCP／ViewerControl に関する項目すべて、state timeline に関する項目すべて、ハングやデッドロックに関する項目すべて）を隣り合わせにし、グループは最も影響の大きい項目の順に、グループ内の項目は影響の大きい順に並べます。 行の順序だけを変更してください。項目を別のサブセクションに移したり、削除したりしないでください。

• 項目をクリック可能にします。 可能な限り、概要と詳細の両方で、項目から機能の使い方を示すドキュメント（使い方ガイド、アーキタイプ／ビューのリファレンスページ、CLI または MCP のリファレンスセクション、Python／JS のリファレンスサイト、docs.rs）にリンクしてください。 changeset にすでに含まれるリンクを再利用し、https://rerun.io/docs/<.md を除いたパス> に変換します。また、リンク先のファイルと #anchor 見出しが存在することを確認してください。 外部の名称にもリンクしてください（例：サードパーティ製ツールをそのドキュメントにリンクします）。 詳細の項目では、行全体ではなく主要な用語にリンクし、末尾のコミット／PR リンクを区別できるようにしてください。

• 破壊的変更ごとに、changeset 内のサブ見出しへのリンクを付けます。 https://rerun.io/docs/changelog/changeset-0-XX#<anchor> を使用してください。 アンカーは、見出しを小文字にし、バッククォートと句読点を除き、スペースをハイフンに置き換えて作成します（rrd::optimize → rrdoptimize）。

• 実際に破壊されたものを明記します。 changeset と CHANGELOG.md の破壊的変更の見出しには、「カタログのステージング」のような置き換え先の新機能ではなく、"WriteChunks を削除" のように、何が破壊されたかを記載してください。 サブセクションの先頭には、削除と移行ガイドへのリンクを置き、その後に置き換え先を記載します。

• 実験的機能と不安定な機能に印を付けます。 changeset と CHANGELOG.md の各新機能について、次のマーカーを確認してください（PREV は直前のマイナーリリースのタグです。例：0.38.0）。

  # Non-blueprint types marked unstable whose definitions changed this cycle
  git diff --name-only $PREV HEAD -- crates/build/re_type_definitions | grep -v /blueprint/ | xargs rg -l 'state = "unstable"'
  # Python APIs in the `rerun.experimental` module
  git log --oneline $PREV..HEAD -- rerun_py/rerun_sdk/rerun/experimental
  # Viewer features behind a flag in `ExperimentalAppOptions`
  git diff $PREV HEAD -- crates/viewer_support/re_viewer_context/src/app_options.rs
  # Docs and docstrings that call something experimental
  git diff --name-only $PREV HEAD -- docs/content rerun_py/rerun_sdk | xargs rg -l -i 'is experimental'
  

  最初のコマンドにファイルが表示されても、その型が新しいとは限りません。該当箇所を実際のエントリと照合してください。 該当する機能ごとに、読者の目に留まる場所でその旨を伝えてください。変更履歴の見出しの先頭に「Experimental」を付け（0.36 の ### Experimental 3D gaussian splat support のように）、今後のリリースで変更される可能性があることを説明する文を追加してください（不安定な型の場合は、データの後方互換性が保たれない可能性があることも説明してください）。 機能がフラグの背後にある場合は、有効にする方法を記載してください。 CHANGELOG.md の概要では、これらのエントリをすべて「Overview & highlights」の末尾にある #### 🧪 Experimental and unstable サブセクションに移動し、変更される可能性があることと、不安定な型の後方互換性が保たれない可能性があることを一行で注記してください。 このサブセクション内のエントリも、影響の大きい順に並べてください。また、各エントリで「Experimental」を繰り返さないでください。 Blueprint の型（re_type_definitions/rerun/blueprint/ 配下の rerun.blueprint.*）は例外です。すべて不安定とマークされていますが、これは Blueprint データの後方互換性が保たれないことだけを意味します。 それだけでは機能が実験的ということにはなりません。新しいビューや Blueprint 設定が実験的となるのは、ほかのマーカーがその機能自体または表示対象のデータアーキタイプに付いている場合に限られます。 同様に、実験的な API で設定するというだけで、Viewer の機能が実験的になるわけではありません。

• 概要の主要機能にメディアを追加してください。箇条書きの下にインデントして、スクリーンショット（または動画の静止画と動画へのリンク）を掲載します。pixi run upload-image が出力する <picture> マークアップを使用してください。 最も視覚的に訴求力のある主要機能を対象に、画像を数点（3～5点程度）追加してください。新しいビューやレンダラー機能は、箇条書きだけより画像のほうが魅力を伝えられます。 変更セットと PR の説明にあるメディアを確認してください。視覚的な機能にメディアがない場合は、ユーザーにスクリーンショットを依頼し、省略しないでください。 すべてのエントリに画像を追加する必要はありません。API、CLI、バグ修正の項目には、通常、画像は不要です。 メディアはすべて static.rerun.io に置いてください。 PR のメディアを再利用するのは、すでに static.rerun.io にあるか、一般公開されている場合に限ります。非公開モノレポの github.com/user-attachments/… リンクは、公開環境では 404 になります。 そのようなファイルは、curl -L -H "Authorization: token $(gh auth token)" <url> でダウンロードし、pixi run upload-image <file> --name <name> でアップロードしてください。 GitHub は外部ホストの <video> をレンダリングしないため、動画の場合は代表的な静止画を抽出し（ffmpeg -ss <t> -i video.mp4 -frames:v 1 still.png）、アップロードしてから、その下に .mp4 へのリンクを配置してください。 フレームを確認し、被写体にカーソルが重なっていないものを選んでください。

5. inbox を空にする

マージ済みの upcoming/*.md エントリを削除してください。ただし、_template.md と今回のリリースに含まれないエントリは残してください。 これらの一時エントリにリダイレクトを追加しないでください。

完了を宣言する前のチェックリスト

• upcoming/ 内のテンプレート以外のすべての項目が、changeset に反映されています。
• changeset に TODO(name) が残っていません。
• 既存の項目に要約やその他の文章が新たに作成されていません。
• CHANGELOG.md の概要が影響度順に並んでおり、視覚的に特に目を引く主要機能のいくつかに static.rerun.io の画像があり、破壊的変更から changeset の小見出しにリンクしています。
• 概要と詳細の各項目で、関連するドキュメントがあるものはリンクされています。
• 詳細の各サブセクションでは、機能ごとに項目がまとめられ、影響度の高い順に並んでいます。
• すべての実験的機能または不安定な機能（機能フラグ、rerun.experimental、blueprint 型以外の型に対する #[rerun(state = "unstable")]、または実験的と説明されている機能）が changeset でその旨を明記され、概要の最後の「実験的および不安定な機能」サブセクションに記載されています。
• pixi run lint-rerun CHANGELOG.md docs/content/changelog/changeset-0-XX.md が成功します。
• 画像と動画は GitHub の添付ファイルではなく、static.rerun.io でホストされています。
• ## Highlights が全体として読みやすくなっているか、問題がある箇所を人間に伝えています。
• CHANGELOG.md のセクションに正しい貢献者のクレジットがあり、誤字がありません。
• upcoming/ には _template.md と、後のリリースに延期された項目だけが含まれています。
• python scripts/ci/check_changelog_redirect.py が成功します（リダイレクト先がこの changeset です）。
• python scripts/ci/check_doc_redirects.py --base origin/main が成功します（upcoming/ 内の項目は対象外で、リダイレクトは不要です）。

補足

• このスキルは、独立した Rerun リポジトリの skills/assemble-changelog にあります。
• rerun-io/rerun 内の同期コミットには Source-Ref トレーラー（reality のマージコミット）が付与されます。generate_changelog.py はこれを元の reality PR にたどり、正しいタイトル、ラベル、貢献者を特定します。
• 次のリリースの changeset は事前に作成されません。未リリースバージョンの空の changeset があると、check_changelog_redirect.py は最も新しい changeset-0-xx.md がリダイレクト先であることを要求するため、失敗します。開発サイクル中に進行中の成果物は upcoming/ のみです。