changelog

変更履歴

明確に定義された変更範囲を、事実に基づくリリース情報にまとめます。リリースされた作業の量と重要性に応じて、項目数、技術的な詳しさ、視覚的な形式を決めます。

範囲を定める

依頼内容とリポジトリから、次の点を判断します。

• 対象のブランチ、タグ範囲、リリース、または期間。
• コミットされていない変更や未リリースの作業を除外するかどうか。
• 対象読者と想定される技術的な詳しさ。
• 出力形式：文章、Markdown、HTML カード、画像、またはその組み合わせ。
• 既存の変更履歴の方針、テンプレート、ビジュアルシステム、過去の事例。

範囲やリリース状況が曖昧な場合に限り、質問します。引き継ぎには正確な範囲を記録します。デプロイの証拠がない限り、マージ済み、コミット済み、または機能フラグで有効化された作業を、公開済みとして説明しないでください。

変更内容を調べる

リポジトリ固有のリリースツールがあれば、まずそれを使用します。なければ、選択した範囲を調べます。

git log --oneline <range>
git diff --stat <range>
git diff --name-status <range>

不明瞭な差分と、関連するテストやドキュメントを読みます。コミットの境界ではなく、ユーザーから見える動作を基準にコミットをグループ化します。

互換性、セキュリティ、信頼性、パフォーマンス、移行、または運用担当者の操作に影響する内部変更も含めます。対象読者にとって影響のない変更は除外します。

候補となる各項目について、次の内容を記録します。

• ユーザーまたは運用担当者への影響。
• 根拠となるコミットまたは差分のパス。
• リリース状況。
• 破壊的変更、移行、セキュリティ、または制限事項の詳細。
• 確信度と、不足しているデプロイの証拠。

対象読者に合わせて草案を作成する

範囲に応じた数の項目を作成します。一貫した成果を示す場合に限り変更をまとめ、レイアウトを埋めるためだけに項目を増やさないでください。

各項目では、何が変わったのか、なぜ対象読者にとって重要なのかを説明します。読者がリリースを導入、デバッグ、移行、または評価するために必要な場合は、実装に関する情報も記載します。

製品の文体と大文字・小文字の表記を維持します。小文字表記、絵文字、スローガン、または利点だけを強調する表現を無理に使わないでください。アイコンやカテゴリラベルが既存のテンプレートに含まれている場合は、一貫性とアクセシビリティを保って使用します。

破壊的変更と必要な対応は、該当する項目のそばに記載します。未検証のデプロイに関する主張は公開文面に含めず、別途報告します。

統計を正確に算出する

指標は役立つ場合にのみ使い、何を数えたのかを正確に示します。コミットごとの変更ファイル数を、重複のないファイル数として提示しないでください。

git の範囲内にある一意のファイルを数える場合：

git diff --name-only <range> | sort -u | wc -l

追加・削除されたテキスト行数には git diff --numstat <range> を使用し、バイナリエントリを考慮します。コミット数、一意のファイル数、変更行数は、ユーザーにとっての価値を示す指標ではありません。

条件に応じてビジュアル成果物を作成する

ユーザーがカードを依頼した場合、またはリポジトリに既存の変更履歴テンプレートがある場合：

1. 既存のアセット、CSS、寸法、過去の出力を調べる。
2. ユーザーがデザイン変更を依頼していない限り、固定されたテンプレートコードを維持する。
3. 実際の項目数と文章の長さに合うレイアウトを選ぶ。
4. リポジトリの命名規則に従って、日付入りの成果物を作成する。
5. 指定された寸法でレンダリングまたはキャプチャする。

テンプレートがない場合は、リポジトリのブランドに関する情報を基に、書体、色、クレジット表記を決めます。暗色の等幅フォントのカードを安易に選ばないでください。セマンティックな HTML を作成し、適切な場合はテキストを選択可能にし、指定されたキャプチャツールとオペレーティングシステムに対応します。

希望するプラットフォームや寸法が不明で、構成に影響する場合は、質問するか、形式を明記したうえで妥当な案を提示します。

出力要件

依頼された成果物に加えて、次を提出します。

Range: [commits/tags/dates and branch]
Audience and channel: [who/where]
Release status: [verified live, released, unreleased, or mixed]
Items: [final count]
Provenance: [item -> commits or paths]
Statistics: [definitions and values, if used]
Artifacts: [paths and dimensions]
Limitations: [deployment or content facts not verified]

文章のみの依頼では、HTML を作成しないでください。監査の依頼では、ユーザーが編集も依頼していない限り、調査結果と提案文の提示までで終了します。

検証

1. 選択した範囲とリリースの根拠を照らし合わせて、すべての主張を再確認します。
2. 「ユーザー向け」というフィルターによって、重要な破壊的変更、セキュリティ、互換性、移行に関する変更が隠れていないことを確認します。
3. 統合された項目が一つの成果を表していること、また、スペースを埋めるためだけの項目がないことを確認します。
4. ラベルに合致し、バイナリファイルも適切に処理するコマンドで、統計を再計算します。
5. 日付、製品名、リンク、バージョン、帰属表示を検証します。
6. ビジュアル成果物を目標寸法でレンダリングし、はみ出し、切り抜き、コントラスト、階層、長い項目の表示を確認します。
7. 利用可能なツールで実際の出力を開くか、レンダリングへのパスを提示します。手動でスクリーンショットを撮る手順を検証の代わりにしてはいけません。
8. デプロイ済み／稼働中であることを直接確認したのか、推測したのかを報告します。