【ITニュース解説】My changelog generator got silent about deletions — git never tells you what went away

システムエンジニアを目指す皆さんにとって、ソフトウェア開発の現場で「Git（ギット）」というツールは避けて通れません。Gitは、プログラムのソースコードなどの変更履歴を管理するための非常に強力なシステムだ。そして、そのGitの変更履歴を基に、ソフトウェアがどのように変わったかをまとめたものが「changelog（チェンジログ）」、つまり変更履歴のことだ。これは、新しいバージョンで何が追加され、何が修正され、何が削除されたのかをユーザーや他の開発者に伝えるための大切なドキュメントである。

今回紹介する話は、ある開発者が自身の経験から得た、このchangelogに関する重要な教訓だ。彼は、Gitのコミット（変更を記録する操作）から自動的にchangelogを生成するAPI（ソフトウェア同士をつなぐ仕組み）を開発した。このツールは、2つの特定のバージョン間の差分を比較して、リリースノートのような変更履歴を作成するものだった。しかし、ある時、問題が発覚した。

ある貢献者が、ソフトウェアのバージョン1.4からバージョン1.5への変更の間に、プログラム全体の一部のモジュールをごっそり削除した。ところが、彼の開発したchangelog生成ツールは、この重要な「削除」について一切触れなかったのだ。エラーメッセージも出ず、警告もなし。ただ、追加された機能や修正された点だけが、あたかも何事もなかったかのようにリストアップされていた。これは、重大な変更を見落とすという、非常に危険な状況だった。

なぜこのような問題が起こったのだろうか。その答えは、Gitの差分（変更点）を確認するコマンドの挙動と、それを処理するツール側の認識にあった。Gitには、git diff --name-statusというコマンドがあり、これは2つのコミット間でファイルがどのように変わったかを教えてくれる。具体的には、「A」はファイルが追加されたこと、「M」はファイルが修正されたこと、そして「D」はファイルが削除されたことを示す。多くのchangelog生成ツールは、当初、追加（A）や修正（M）された変更だけを「興味深い変更」として扱っていた。今回の開発者のツールも同様で、削除（D）のステータスを持つ変更を、意図せず「興味のない変更」としてフィルターにかけてしまい、何も言わずに無視していたのだ。

しかし、この「削除」こそが、しばしば最も破壊的で、深刻な影響をもたらす変更となり得る。例えば、機能を追加したり、既存の機能を修正したりする変更は、新しい振る舞いを加えるか、既存の振る舞いを少し変える程度で済むことが多い。しかし、プログラムの一部やAPIのエンドポイント（外部からアクセスする窓口）が削除された場合、それを使っていた他のシステムやアプリケーションは突然機能しなくなり、エラーを発生させる。これは、夜中に緊急対応が必要になるような、非常に重大な事態を引き起こす可能性がある。開発者は、関数名の変更が単なる置換作業で済むのに対し、APIエンドポイントの削除は緊急事態につながると表現している。

この問題を解決するための方法は、シンプルながらも非常に効果的だった。それは、「D」（削除）というステータスを持つ変更を、追加や変更と同等、あるいはそれ以上に重要な「第一級の変更」として扱うことだ。そして、単に削除があったと伝えるだけでなく、「Removed POST /v1/legacy-auth」（POST /v1/legacy-authが削除されました）のように、追加（「Added dark mode」：ダークモードが追加されました）よりも明確で、大きな言葉でその事実を報告するように修正した。これにより、changelogを読む人が、何が失われたのかを一目で理解できるようになった。

この経験から、開発者はもう一つの重要な教訓を得た。それは、「コミットメッセージは常に真実を語るとは限らない」ということだ。先述のモジュールが削除されたコミットのメッセージは、「Refactor auth」（認証部分のリファクタリング）だった。リファクタリングとは、プログラムの内部構造を改善する作業で、通常は外部から見た機能に大きな変更はない。このメッセージだけでは、重要なモジュールが削除されたことまでは到底分からない。開発者は、コミットメッセージは急いで書かれたキャプションに過ぎず、Gitの「差分（diff）」こそが、プログラムの変更に関する唯一の「真実の源」であると気づいた。そのため、彼のchangelog生成ツールは、今では差分が実際に示す内容を最も重要な情報として前面に出し、コミットメッセージは補足情報として扱うように変更された。

世の中には、他にも多くのchangelog管理ツールが存在する。例えば、「release-drafter」や「semantic-release」といったツールだ。これらは、コミットメッセージに特定のルール（コミット規約）を設けることで、changelogを自動生成する。例えば、「BREAKING CHANGE: 」というフッターや、「feat!: 」というプレフィックス（接頭辞）をメッセージに含めることで、破壊的な変更や新機能であることを識別する。このような方法は、開発チームが厳格な規律を持ってコミット規約を守る場合には非常にうまく機能する。

しかし、実際の開発現場は必ずしも規律正しいわけではない。多くのリポジトリでは、複数のコミットを一つにまとめる「squash-merge」が行われたり、過去の履歴を書き換える「force-push」が使われたり、あるいは「fix stuff」（いろいろ修正）のような曖昧なコミットメッセージが書かれたりすることが頻繁にある。このような「規律のない現実」において、コミット規約は「希望的観測」に過ぎない。それに対して、Gitの差分は、実際にコードベースで何が起こったかを示す「事実」である。開発者のAPIは、この事実に基づいてchangelogを生成することで、規約に依存しない堅牢なツールとなっている。

この一連の経験から得られる最も大切な教訓は、「削除された内容を示さないchangelogは決して信用してはならない」ということだ。もしchangelogが、何がコードベースから消えたのかを教えてくれないのであれば、それは真のchangelogではない。それは単なる「プレスリリース」、つまり良いニュースだけを伝える宣伝文句に過ぎない。システムエンジニアを目指す皆さんにとって、ソフトウェアの変更履歴を正確に理解し、伝える能力は非常に重要だ。この話は、そのためにGitの差分情報を深く理解し、あらゆる種類の変更、特に削除という破壊的な変更に注意を払うことの重要性を教えてくれる。

この重要な改善を経て、開発者は彼のツールを https://x402.freeq.one/tools/changelog_git.html として公開している。この経験は、単にツールを修正しただけでなく、ソフトウェア開発における情報伝達の原則と、Gitというツールの本質的な使い方についての深い理解を与えてくれるものだ。