チェンジログとは何か、そして何が含まれるべきか

チェンジログとは、製品で何が変わったかを日付付きで記録したもので、それをリリースしたチームのためではなく、変更によって影響を受ける人々のために書かれる。各エントリは一つの変更を名指しし、それがいつ有効になったかを述べ、読者がそれについて何をすべきかを述べる。ほとんどのエントリでは、それは何もしなくてよいということだ。この最後の部分こそが、チェンジログをコミットログから分けている。コミットログはコードを書いた人々のための記録であり、チェンジログはそれを使う人々のための記録だ。

チェンジログとは正確には何か

日付付きのエントリのリストで、最新のものが先頭にあり、それぞれが一つの変更を読者が確認できる言葉で説明する。チームが何を作ったかではなく、今何が違うかだ。「請求サービスをリファクタリングした」はコミットメッセージである。「請求書は税金を別の行として表示するようになった」はチェンジログのエントリだ。なぜなら、読者が自分のアカウントで確認できることを伝えているからだ。

このフォーマットは古く、意図的にシンプルだ。リリースごとまたは日ごとの見出し、その下に短いリスト、時にはカテゴリのラベルが付く。Keep a Changelogはこの形式で最も引用される仕様であり、それが存在するのは、仕様を飛ばすほとんどのプロジェクトが代わりにコミット履歴をそのまま吐き出すことになり、それが読者の持ってきた質問とは違う質問に答えてしまうからだ。

この五つは実際には重なり合うが、同じ文書ではなく、その違いは読むときに誰がそれを手にしているかにある。チェンジログは後で検索され、再びリンクされるために作られたものであり、そのためエントリは他のどれよりも日付と安定したURLを必要とする。

チェンジログのエントリには実際に何が含まれるのか

四つのこと、この順序で。何が変わったか、利用者や呼び出し側が気づくであろう言葉で表現されたもの。いつ有効になったか。どのカテゴリに属するか(added、fixed、changed、removedが一般的な四つ)。そして重要な場合、読者がそれについて何をすべきか。詳細へのリンクは歓迎される。内部的な正当化の段落はそうではない。読者はなぜかを聞いていない、何かを聞いているのだ。

## 2026-09-07

### Added
- 請求書は顧客のアカウント通貨で、税金を別の行として表示するように
  なった。

### Fixed
- レポートをCSVとしてエクスポートする際、レポートが10,000行を超えても
  最後の行が失われなくなった。

このフォーマットは二行の更新から一つのリリースにおける百のエントリまで、構造を変えずに拡張できる。そしてこれこそがフォーマットが機能しているかどうかの本当のテストだ。忙しい週も静かな週も同じように読めるかどうか。

誰がチェンジログを書くのか、そしていつか

変更を行った本人が、それがリリースされる瞬間に書く。一週間後にチケットから再構成する技術ライターではない。コードに触れた人は利用者にとって実際に何が変わったかを知っている。後から書かれた要約は、実際にリリースされたものではなくチケットを説明する傾向があり、それは通常、実際の範囲より広いか狭い。一部のチームは、エントリが公開される前にレビューのステップを追加する。主に紛れ込んだ内部の言葉遣いを捕まえるためだ。そのレビューは、エントリが同じ日に出るくらい十分速くなければならない。

チェンジログはどこに置かれるべきか

安定したURLの独自のページに、フィードとして配信される。設定メニューやコードホストのリリースタグに埋もれていると、どこを見ればいいかすでに知っている人にしか届かない。公開ページはサポートチケットからリンクされ、レビューで引用され、購読されることができる。フィードはページと同じくらい重要だ。ある製品のチェンジログを月に一度確認する読者は稀であり、それを購読する読者はそうではなく、フィードだけが後者に応えている。

リリースノートとどう違うのか

この二つは常に混同され、混ぜ合わせるとどちらの読者にもうまく機能しない文書になるほど異なっている。チェンジログ対リリースノートがその違いを完全に扱っている。簡単に言えば、チェンジログは完全で年代順の記録であり、リリースノートは更新が持つ価値があるように聞こえるよう書かれた厳選された部分集合だ。製品は通常両方を必要とし、読者の一日の異なる瞬間に向けられている。

何がチェンジログを読む価値のあるものにするのか

自らの範囲についての具体性と誠実さだ。「様々なバグ修正」は、読者にページを開くのをやめさせる文だ。なぜなら確認できることを何も約束していないからだ。たとえ小さな修正であっても、変わった正確な挙動を名指ししたエントリこそが、購読を生かし続けるものだ。この規律は省略されるものにも当てはまる。成功だけを発表し、壊れていた何かの修正を決して発表しないチェンジログは、チェンジログの姿をしたマーケティングのように読め、読者はそれに気づく。

バージョニングの規律も重要だ。セマンティックバージョニングとあなたのチェンジログは、バージョン番号とエントリがどう一致すべきかを示していて、バージョン履歴を眺める読者が二つの異なる信号ではなく同じ信号を二度受け取れるようにする。

チェンジログはどう生成されるのか

二つの方法があり、実際のほとんどの構成はその組み合わせだ。自動生成はコミットメッセージを読み、通常Conventional Commits形式で、誰も出力に触れずにそれをエントリに変換する。Conventional Commitsからチェンジログへがそのパイプラインを扱っている。キュレーションされた生成とは、誰かが手作業で各エントリを書くか編集することを意味する。自動化された出力はより速く、マージされたプルリクエストを決して見逃さないが、あいまいなコミットメッセージをそのまま継承してしまう。だから自動化する多くのチームでも、生の出力をそのまま見せるのではなく、公開前に軽い編集の段階を維持している。

FAQ

すべての製品にチェンジログが必要か? 変更によって影響を受ける利用者がいる製品なら、SaaSアプリでも、社内ツールでも、公開APIでも必要だ。形は適応する(APIチェンジログは消費者向けアプリのものとは違う読み方をする)が、必要性は変わらない。

ソフトウェア用語でチェンジログとは何か? 上と同じ定義だ。ソフトウェアで何が変わったかの、日付付きで年代順のリストであり、それを作った人ではなく使う人のために書かれる。

チェンジログはコミットから自動生成できるか? できる。多くのチームがまさにそれを行っていて、通常はConventional Commits形式のメッセージからだ。トレードオフは、生成されたエントリが元になったコミットメッセージと同じくらい明確でしかないことで、だから公開前のレビューの通過が言い換えが必要なものを捕まえる。

チェンジログはバージョン履歴と同じものか? 用語が互換的に使われるくらい近い。バージョン履歴は時に説明なしのバージョン番号と日付のリストにすぎないが、チェンジログは常に何が変わったかを含む。

この記事の技術的な記述は第三者による確認を受けていません。誤りがあればお知らせください。修正します。

changeloopの関連ページ： changelogの例, 開発者向けドキュメント