本番デバッグを救う証跡管理
本番環境でバグが発生した。データが壊れている。ユーザーから苦情が来ている。オンコール担当の開発者がコミットログを開くと、そこには「fix bug」「update」「wip」といったメッセージが延々と並んでいる。その開発者は変更されたファイルをひとつひとつ開き、各変更の意図を推測し、正しいコミットにたどり着くことを願うしかない。これこそ、コミットの質の低さが5分の調査を2時間の苦行に変える瞬間である。
開発者がソース管理に変更を保存するたびに、コミットが作成される。コミットは記録である。変更されたコード、変更者、変更日時、そして開発者が書いたメッセージが格納される。このメッセージはしばしば後回しにされるが、問題発生時には最も価値ある情報のひとつとなる。
有用なコミットメッセージの条件
役に立たないコミットメッセージと有用なものの違いは単純だ。有用なメッセージは「何が変わったか」だけでなく「なぜ変わったか」を説明する。コード自体が「何が変わったか」を示している。差分（diff）を読めばわかる。しかし差分からは、なぜその変更を行ったのかを読み取ることはできない。
次の2つのメッセージを比較してほしい。
- 「update format tanggal」
- 「新しいライブラリが以前のフォーマットをサポートしていないため、日付フォーマットをDD/MM/YYYYからYYYY-MM-DDに変更」
2つ目のメッセージはコンテキストを伝えている。日付解析に関連するバグが発生した場合、どのコミットを確認すべきか、なぜ変更が行われたかが即座にわかる。変更者を探し出して作業を中断させ、3週間前の記憶をたどらせる必要はない。
優れたコミットメッセージは単純なパターンに従う。「何が変わったか」と「なぜ変わったか」を記述する。「何」は簡潔でよい。「なぜ」こそが、デバッグ、コードレビュー、新メンバーのオンボーディングにおいて時間を節約する部分である。
ナビゲーションツールとしてのタグ
リリース追跡にはコミットだけでは不十分だ。コミット履歴には数百から数千のエントリが存在する可能性がある。バージョン2.3.0がリリースされた正確なポイントを見つけるには、マーカーがなければ長いリストをスクロールするしかない。
タグはこの問題を解決する。タグは特定のコミットに付与されるラベルであり、重要な瞬間を示す。最も一般的な用途はリリースのマーキングである。v1.2.3やv2024.05.15のようなタグは、特定の時点でどのバージョンのコードが動作していたかを正確に示す。
多くのチームはタグにセマンティックバージョニングを採用している。パターンはメジャー、マイナー、パッチの3つの数字で構成される。メジャー番号は後方互換性のない破壊的変更がある場合に変更される。マイナー番号は新機能が追加されたが、旧バージョンでも動作する場合に変更される。パッチ番号はバグ修正のみの場合に変更される。バージョン番号を見るだけで、アップグレードのリスクの大きさがわかる。
タグはロールバック時にも役立つ。デプロイに失敗した場合、どのバージョンが以前正常に動作していたかを把握する必要がある。タグ付きのコミットは明確な目標を示す。ユーザーが待っている間に推測したりコミット履歴を検索したりする必要はない。
コミットとタグをリリースノートに結びつける
タグはバージョンを示す。リリースノートはそのバージョンに含まれる内容を伝える。リリースノートは長くする必要はない。チームとユーザーにとって重要な変更点、つまり追加された新機能、修正されたバグ、設定変更やデータベースマイグレーションなどの特別なアクションが必要かどうかをリストアップすればよい。
優れたコミットメッセージ、一貫したタグ、明確なリリースノートを組み合わせることで、完全な監査証跡が得られる。本番環境で問題が発生した場合、まずリリースノートを確認して怪しい変更を特定する。次にタグを確認して正確なコミットを見つける。そしてコミットメッセージを読んで変更理由を理解する。すべての情報が、誰かに尋ねることなく入手可能である。
この監査証跡はデバッグだけのためのものではない。コンプライアンスチームや外部監査人が、誰がいつ何を変更したかを知る必要がある場合もある。明確なコミットと適切なタグがあれば、人々の記憶から話を再構築することなく、変更の全履歴を示すことができる。
チームのための実践的チェックリスト
あなたのチームがまだこれらの習慣を身につけていないなら、今日から始められる短いリストを以下に示す。
- コミットメッセージには「何が変わったか」だけでなく「なぜ変わったか」を書く
- すべてのリリースにセマンティックバージョニングに従ったバージョン番号のタグを付ける
- 各バージョンの変更点をリストアップしたリリースノートファイルを維持する
- リリースノートに破壊的変更やマイグレーション手順があれば必ず記載する
- すべてのリポジトリで同じタグ形式を使用し、誰もが期待値を把握できるようにする
具体的な教訓
次にコミットメッセージを書くときは、本番障害の最中にそれを読む人のことを想像してほしい。あなたに電話しなくても問題を修正できるようなメッセージを書くのだ。そのひとつの習慣を一貫して実践すれば、コミット履歴はノイズから信頼できるデバッグツールへと変わる。