engineering-change-descriptions

エンジニアリング変更の説明

変更の説明は、恒久的なエンジニアリングの履歴です。レビュー担当者が現在その変更を理解できるようにし、将来のメンテナーが後から見つけて理解できるようにする必要があります。

Google Engineering Practices Documentation、特に「Writing good CL descriptions」を参考にしています。出典：https://google.github.io/eng-practices/review/developer/cl-descriptions.html。ライセンス：CC-BY 3.0。

適切な説明で答えるべきこと

• 何を変更しましたか？
• なぜ変更しましたか？
• コードからは明らかでない背景、制約、トレードオフは何ですか？
• どのようにテストしましたか？
• レビュー担当者が把握しておくべきリスク、移行、ロールバック、フォローアップはありますか？

理由が明らかでない場合は、小さな変更にも背景を添えてください。

1 行目

1 行目は、次の条件を満たす必要があります。

• バージョン管理の履歴に単独で記載しても意味が通じる。
• 短く、具体的で、変更内容に焦点を当てている。
• コミットまたは CL のタイトルを書く場合は、命令形にする。
• 「バグ修正」「整理」「フェーズ 1」「その他」「ヘルパーを追加」のような曖昧な表現を避ける。
• 本文がある場合は、1 行目の後に空行を入れる。

本文

役立つ背景情報だけを記載してください。

• 解決する問題。
• この方法を選んだ理由。
• ユーザーまたは開発者から見える動作の変更。
• 重要な実装上の補足。
• 既知の制限事項や今後の作業。
• バグ ID、課題へのリンク、ベンチマーク結果、設計ドキュメント、移行ドキュメント、ロールアウト計画。
• 後にアクセスできなくなる可能性のあるリンクについて、理解に必要な背景情報。
• 適切な場合は、テスト用コマンドと結果。

提出前に、レビューで変更した後の説明を読み返し、最終的な差分と一致していることを確認してください。

テンプレート

標準的な PR

[Imperative one-line summary]

## Why
[Problem, user need, production issue, maintainability reason, or design context.]

## What Changed
- ...
- ...

## Testing
- ...

## Risk / Rollback
- Risk:
- Rollback:

小さな変更

[Imperative one-line summary]

[One paragraph explaining why this change exists and any non-obvious context.]

Testing: [command or manual check]

リファクタリング

[Describe the structural change and what it replaces]

This prepares for [future change] by [specific reason], without intentionally changing behavior.

Testing: [existing or new tests that protect behavior]

生成または機械的な変更

[Describe the mechanical rewrite]

Generated by [tool/version/command] to [reason]. Manual edits: [none/list].

Verification: [format/test/build command]

書き換えのチェックリスト

既存の説明を改善する場合：

1. 差分から実際の動作を把握する。
2. 曖昧な 1 行目を具体的な操作に置き換える。
3. 不足している理由を追加する。
4. 役立つ課題へのリンクとテストの証拠を残す。
5. レビュー担当者や将来のメンテナーの役に立たないプロセス上の雑音を削除する。

よくある間違い

• 理由を説明せず、実装だけを記述する。
• 将来、検索したときに似た変更と区別できないタイトルを付ける。
• 重要な背景情報を外部リンクだけに頼る。
• レビューによって差分が大きく変わった後も、説明を更新しない。
• リスク、制限事項、ロールアウト要件を、不都合だからという理由で隠す。