writing-changelogs

チェンジログの書き方

前提として必須: technical-writing スキル（ハードルール、真実ルール、スタイル）。

概要

チェンジログの主題は変更であり、現在の状態ではありません。マイグレーションのドキュメントとリリースノートも、同じ主題を持つ別のドキュメント種別です。チェンジログは歴史的なものであり、エントリは決して書き換えず、追記するだけです。

いつ呼び出すか、いつ呼び出さないか

意味のある変更（機能、実際の規模の修正、削除）を出荷した後、リリースノートを書くとき、または何を出荷したかを要約するときに呼び出します。些細な編集（おおよそ変更ファイル 3 つ、またはコミット 3 つ）では呼び出さないでください。また、既存のエントリを書き換えたり削除したりしないでください。

ルール

• 出荷した変更ごとに 1 つのエントリ、新しいものが先、ISO 日付、バージョンが存在する場合はバージョンごとにグループ化します。
• ファイルが使用している場合は標準カテゴリ: Added / Changed / Deprecated / Fixed / Removed / Security。Deprecated のエントリには削除日と代替を記載します。
• 破壊的変更はエントリの先頭に置き、カテゴリの上に記載し、それぞれに必要なマイグレーション対応を明記します（マイグレーションガイドが存在する場合はリンクします）。
• 実装の詳細よりもユーザーに見える影響を優先します。
• 現在形、能動態、読者が知らないであろう専門用語は避けます。
• 関連する変更をグループ化し、既存のエントリを重複させないでください。
• 追加だけでなく削除も記録します。
• リリースノートは、同じ事実を読者向けに切り出したものです: 何が変わったか、誰に影響するか、どう対応すべきか。チェンジログはエンジニアに向けて書き、リリースノートはシステムのユーザーに向けて書きます。どちらも同じ情報源に基づき、互いに矛盾してはなりません。

エントリの形

ドキュメント種別の例外: 以下で必須とする太字のリード文は、太字リードの箇条書きに対する共通の禁止を上書きします。この例外は、チェンジログの成果と、名前を挙げた known issue、deferred item、omission のカテゴリにのみ適用されます。繰り返しのラベルと値の箇条書きは、ほかの場所では引き続き禁止です。

成果を述べる太字のリード文、次に根本原因、次に修正、正確な名称はインラインで:

- **Reference-to-video routing fixed.** The resolver only knew three operation
  kinds, so requests with reference media routed to image-to-video. A
  `hasReferenceMedia()` check now gives reference-to-video a higher-priority
  branch.

Fixed のエントリは差分ではなく、障害の発生のしかたを説明します。太字のリード文はユーザーへの影響を伝え、これにより読者は変更リストをトリアージできます。

誠実さのための慣例

3 つのエントリ種別がチェンジログを引用可能にします:

• 既知の問題 この変更では表面化したが修正していないもの。そのように明記します。
• 先送り項目 まだ負っているもの（「webhook キーを復元するにはデプロイが 1 回必要」）。
• 意図的な省略 カテゴリごとに説明し、同じ省略が再び蒸し返されたり、見落としと誤解されたりしないようにします。

正確にその対応が完了し確認されていない限り、実装済み、デプロイ済み、検証済みと決して記載しないでください。実装済み（リポジトリ内）とデプロイ済み（稼働中）と外部検証済みを区別してください。

引き継ぎ / 完了サマリー

完了した作業をレビュアーや運用担当者に引き継ぐには、次のセクションを順に扱います:

1. この作業が存在する理由
2. 何を出荷したか
3. どこをレビューすべきか（レビュアーが判断する前に理解すべき決定）
4. 検証状況: 正確なコマンドとその結果、単なるチェックマークは不可
5. 正直な注意点と自分が間違えたこと
6. 残存するリスクとやってはいけないこと
7. 状態と負っているもの（マージ済みだがプッシュしていない、マイグレーション、順序を誤った場合の結果を伴う順序付きの手順）