Gitタグ、リリース、そしてあなたのチェンジログ
1分で読めます
Gitタグ、リリース、チェンジログのエントリは、同じ出来事についての三つの異なる記録であり、それらを混同することはチェンジログを実際にリリースされたものから静かにずらしていく。タグはコミットに印をつける。リリースはそのタグをアーティファクトと説明でパッケージ化する。チェンジログのエントリは、リポジトリの外にいる読者が使える言葉で、何が変わったかを説明する。それらは通常時間的に近接して起こり、まさにそれゆえに三つのステップではなく一つのステップとして扱うのが簡単になり、まさにそれゆえに誰かが「v2.4では何がリリースされたのか」と尋ねて、正直な答えが本物の掘り起こしを必要とするまで、そのギャップは何か月も後になって初めて見えるようになる。
三つの間の実際の違いは何か
| 記録 | 存在する場所 | 対象読者 |
|---|---|---|
| Gitタグ | リポジトリ、参照として | まさにそのコミットをチェックアウトする誰でも |
| リリース | コードホスト(GitHub、GitLab) | ビルドをダウンロードする誰でも |
| チェンジログのエントリ | 製品自身のチェンジログ | リポジトリだけでなく製品を使う誰でも |
タグは三つのうち最も機械的なものだ。git tag v2.4.0、それで終わりで、それが何を含むかを何かが説明する必要は一切ない。リリースは説明を追加し、通常はダウンロード可能なアーティファクトも追加するが、その対象読者は依然としてリリースページが何かを知っている開発者たちだ。チェンジログのエントリは三つのうち唯一、リポジトリを決して開かないかもしれない読者のために書かれたものであり、だからこそ最も編集上の注意を必要とし、締め切りの圧力のもとで最も飛ばされやすい。
すべてのGitタグはチェンジログのエントリを必要とするか
いいえ、そして両者を1対1で扱うのはよくある間違いだ。タグは内部のマイルストーンや、リリース候補や、ほとんどの利用者に決して届かないホットフィックスを示すことがある。それらのどれも必ずしも公開のエントリを必要としない。テストは、そもそも何かがチェンジログに属するかどうかを決めるのと同じものだ。利用者や呼び出し側がそれに気づくか、気にするだろうか。ほとんどのタグはこのテストに合格する。CIパイプラインを起動するためだけに作られたタグのようないくつかは、決して合格しない。
すべてのチェンジログのエントリは自分自身のタグを必要とするか
常にではなく、ここで継続的にデプロイするチームとバージョン管理されたパッケージをリリースするチームが分かれる。一日に何度もデプロイするSaaS製品は、デプロイごとに1対1のタグなしで、複数のデプロイを一つの日付付きチェンジログのエントリの下にグループ化できる。パッケージレジストリで公開されるライブラリは、通常公開されたバージョンごとに一つのタグを必要とする。GoモジュールとSwift Package Managerはタグそのものからバージョンを解決する。npmやPyPIではレジストリが公開されたバージョンを保持しており、タグは誰もがそのバージョンをソースに対応づけるための手段だ。独立してバージョン管理される複数のパッケージを持つリポジトリは、これをリポジトリ全体で一度ではなくパッケージごとに決める必要があり、モノレポのチェンジログがタグの接頭辞とチェンジログの範囲をフォルダの境界ではなくパッケージの境界に沿わせる方法を扱っている。セマンティックバージョニングとあなたのチェンジログは、バージョン番号自体がチェンジログのカテゴリにどうマッピングされるべきかを扱っている。タグは、バージョン番号を実際のコードに対して検証可能にする仕組みだ。
リリースの説明はチェンジログのエントリとどう関係すべきか
両者は同じテキストであり得るが、それは両者の対象読者が本当に同じ場合に限られ、それは見た目より稀だ。コードホスト上のリリースページはほとんど開発者だけに読まれる。製品にチェンジログを読む非技術的な利用者もいる場合、リリースの説明をそのまま複製することは、平易な言葉のバージョンを必要としていた読者に内部用語やコード中心の言い回しを送ることになる。最も綺麗なパターンは、チェンジログのエントリを主要な、読者志向のアーティファクトとして書き、リリースの説明はそれにリンクするか、すでにそこに慣れている読者向けに、より短く技術的な要約を保持することだ。
# リリース v2.4.0 (GitHub、開発者向け)
レポートのパイプラインを新しい集計エンジンに引き上げる。顧客向けの
要約はチェンジログを参照: https://example.com/changelog#v2.4.0
## 2026-09-07 (チェンジログ、顧客向け)
### Added
- レポートは今や100万行を超えるアカウントでも1秒未満で読み込まれる
ようになった。同じリリース、二つの文書、それぞれ自分自身の読者のための自分自身の言い回しで。
チェンジログのエントリは実際どこから来るのか
二つの出発点からで、ほとんどの実際のパイプラインは両方の混合だ。タグの時点でコミットメッセージから生成することができ、これは速く、マージされたプルリクエストを決して見逃さない。Conventional Commitsからチェンジログへがそのパイプラインを完全に扱っている。あるいはタグから完全に切り離されて手で書くこともでき、コードがマージされる瞬間ではなく、機能が完成したと見なされる瞬間に合わせて調整される。生成されたエントリは一貫しているが、あいまいなコミットメッセージをそれぞれ継承する。手で書かれたエントリはより明確だが、実際にそれを書く誰かが必要だ。自動化する多くのチームでも、生の出力をそのまま見せるのではなく、それが公開のエントリになる前に、生成されたテキストに軽い編集の段階を維持している。それはKeep a Changelog、実践編が推奨するのと同じ規律であり、生のテキストがもともとどこから来たかにかかわらずだ。
三つが同期しなくなると何が壊れるのか
読者が最初に確認したものへの信頼だ。対応するチェンジログのエントリなしで存在するタグは、チェンジログの読者の側から見ると、その週何も起こらなかったかのように見える。対応するタグやリリースのないチェンジログのエントリは、本番の問題をデバッグしている誰かが、エントリが公開されたときにライブだったまさにそのコードをチェックアウトすることを不可能にする。解決策は完璧な自動化ではなく、その対応関係のための単一の信頼できる情報源だ。たとえそれがリリースプロセス自身のチェックリストにすぎなくても、リリース可能な変更がそれを導入する同じコミットやプルリクエストで三つすべてを受け取ると言う一つの場所だ。
FAQ
チェンジログのエントリはGitタグから自動的に生成されるべきか? 出発点にはなり得るが、タグだけでは読者向けの説明を一切運ばず、コミットの範囲だけを運ぶ。自動生成は、使えるものを生み出すために、タグの存在だけでなく、その範囲内のコミットメッセージを読まなければならない。
すべてのリリースにタグを付けなかったらどうなるか? その場合、チェンジログのエントリが主要な記録になり、それでも日付を持つべきで、製品にバージョンがあるならバージョン番号も持つべきだ。対応するタグがなくても、読者が後で参照できるものとしてエントリが残るようにするためだ。
プレリリースのタグ(v2.4.0-rc.1のような)はチェンジログのエントリを持つべきか?
一般的には持つべきでない。リリース候補は内部テストやベータテストのためのものであり、それに対するチェンジログのエントリは、読者に、説明された通りには決してリリースされないかもしれないバージョンのエントリを期待するよう訓練してしまう。エントリは一般提供に達したタグのために取っておくこと。
一つのチェンジログのエントリが複数のGitタグをカバーできるか? できる、そして頻繁にタグを付けるチームにとっては、しばしばそうすべきだ。関連するタグを、機能を複数の読書にわたって断片化するタグごとの薄いエントリを公開する代わりに、正味の変更を説明する一つの日付付きエントリの下にグループ化すること。
この記事の技術的な記述は第三者による確認を受けていません。誤りがあればお知らせください。修正します。