エンジニアリング

Keep a Changelogの解説とCHANGELOG.mdテンプレート

1分で読めます 更新

Keep a Changelogは、CHANGELOG.mdのための一ページの慣習だ。最新バージョンを先頭に、バージョンごとに一つのセクション、番号とISO日付を持ち、項目は六つのタイプ(Added、Changed、Deprecated、Removed、Fixed、Security)の下にグループ化され、リリース間の項目のために先頭にUnreleasedセクションがある。それを引用する多くのチームは、その三分の二ほどを実装し、省略される三分の一こそが、ユーザーを守る三分の一だ。

Olivier Lacanは2014年にKeep a Changelogを、多くのソフトウェア関連の文章よりも良く年を重ねた一文とともに公開した。don’t let your friends dump git logs into changelogs。十年後の今、これはソフトウェアのこの片隅が持つ、標準に最も近いものだ。要約ではなく原文を読む価値がある。この記事は省略される部分についてのものだ。

Keep a Changelogは何を求めているか

リポジトリのルートにあるCHANGELOG.md、最新のものを先頭に、バージョンごとに一つのセクション。各バージョンは番号とISO日付を持ち、その項目を六つのタイプの下にグループ化する。

タイプ何のためか省略したときのコスト
Added新機能何もない。誰もこれを省略しない
Changed既存の動作の変更読者はエラーから動作の変更に気づく
Deprecated削除される予定の機能削除が計画されたイベントではなくインシデントになる
Removedこのリリースで削除された機能誰も削除とバグを区別できない
Fixedバグ修正何もない。これも誰も省略しない
Security脆弱性それを探していた唯一の読者が見つけられない

さらに先頭にUnreleasedセクションがあり、マージされた瞬間に項目を置く場所があり、誰でも次に来るものを見られる。

これがほぼすべてだ。残りは根拠にすぎない。項目は人間のためであり、変更ごとに一つの項目であり、ファイルはログではなく文書である、というものだ。

Keep a Changelogのファイルはどんな見た目か

この形式の完全なCHANGELOG.mdを示す。Unreleasedセクション、ISO形式の日付を持つ二つのリリース済みバージョン、六つのタイプすべて、そして各バージョン見出しをクリックできるようにする末尾の比較リンクだ。見出しは、仕様どおり、どの言語でも英語のままにする。項目は、読者が使う言語で書けばよい。

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog][kac],
and this project adheres to [Semantic Versioning][semver].

## [Unreleased]

### Added
- レポートページから、任意のレポートをCSVで出力できる。

## [1.1.0] - 2026-10-02

### Added
- 請求書イベント用のWebhook。

### Changed
- レポートページは、全行ではなく最新の50行を先に読み込む。

### Deprecated
- `GET /v1/export` は2026-12-01に動作しなくなる。
  代わりに `GET /v2/exports` を使う。

### Removed
- XMLエクスポート。代わりにCSVエクスポートを使う。

### Fixed
- 免税アカウントの請求書に、税額ゼロの行が出なくなった。

### Security
- セッションCookieを `SameSite=Lax` で送信するようになった。

## [1.0.0] - 2026-08-14

### Added
- 最初の公開リリース。

[kac]: https://keepachangelog.com/en/1.1.0/
[semver]: https://semver.org/spec/v2.0.0.html
[unreleased]: https://github.com/acme/app/compare/v1.1.0...HEAD
[1.1.0]: https://github.com/acme/app/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/acme/app/releases/tag/v1.0.0

Keep a Changelogのどの部分が省略されるか

Unreleasedセクション、次に六つのタイプのうち四つ(Securityもその一つ)、この順番で。

Unreleasedが最初に消える。 これは期限のないセクションなので、その維持が最初に止まるものであり、それが消えると項目はリリース時にコミット履歴から書かれるようになる。それはまさに、仕様が冒頭で警告しているgit logのダンプそのものであり、段階的に到達する結果だ。チェンジログの自動化は、大部分がこのセクションを、誰も覚えていなくても生かし続けることについてのものだ。

六つのタイプが二つに崩壊する。 実際のチェンジログのほとんどはAddedとFixedに落ち着く。ChangedとDeprecatedは、誰が何に依存していたかについての判断を要求するからだ。その判断こそが価値ある部分だ。特にDeprecatedは、未来についての約束である唯一のタイプであり、それを省略することが、削除がインシデントに変わる仕組みだ。その約束を守るための仕組みはAPIの非推奨化にある。

Securityが分離されなくなる。 Fixedの下にまとめられたセキュリティ修正は、それを探していた唯一の読者には見えない。修正が些細なものであっても、特に注目を集めたくないと思うときこそ、それを分離しておくべきだ。

仕様が答えていないことは何か

これはファイル形式だ。それを採用した直後に直面する疑問については何も語っていない。

  • 誰かがどうやってそれを知るのか? リポジトリ内のファイルは貢献者に届く。GitHubを一度も開いたことのない顧客には届かない。
  • バージョンのないプロダクトはどうか? 継続的にデプロイされるサービスには、グループ化できるv4.2.0が存在しない。多くのチームはそれを日付で代替しており、それは機能するし、仕様はそれを容認も禁止もしていない。
  • 誰が項目を書くのか? 仕様は人間がそれをすると想定している。いつ書くかは述べていない。
  • 複数の読者はどうか? 一つのファイルは開発者に役立つ。同じ内容を非技術系の管理者に役立てることはできず、彼女のために手動で再フォーマットすることが重複の始まりになる。チェンジログ対リリースノートは、仕様があなた自身に委ねている分割だ。

このアイデアのより厳格な派生であるCommon Changelogは、その一部を厳しくしている。特定の項目の言い回しを禁止し、変更へのリンクを要求し、読者が誰であるかについて明確な意見を持っている。Keep a Changelogの緩い部分こそが、あなたのチームが常に議論している内容なら、読む価値がある。

git logをダンプせずにKeep a Changelogを自動化できるか

できる。構造化されたコミットから下書きを導出し、タイプを事前入力した状態でUnreleasedに配置し、リリースが切られる前に人間が言い回しを編集することを要求する。仕様の警告は出力についてのものであり、ツールについてではない。コミットから下書きを導出することは問題ない。編集されていないその下書きを公開することが、それが反対しているものだ。

機械は収集とフォーマットを担当し、それは得意な分野だ。人間は選定と言い回しを担当し、それは機械が得意でない分野だ。Conventional commitsは、これが依拠する二層構造と、どのコミットタイプが上記の六つのカテゴリーのどれに対応するかを扱っている。私たちのチェンジログツールのまとめは、収集の半分について何が存在するかをカバーしており、無料のチェンジログジェネレーターは、貼り付けたコミットログをグループ化した下書きにしてくれるので、Unreleasedに入れる前に編集できる。

Keep a Changelogはどこで十分でなくなるか

配布のところで止まる。Keep a Changelogは「このファイルはどう見えるべきか」への良い答えだ。「私たちのユーザーは何が変わったかをどうやって知るのか」への答えではない。リポジトリ内のMarkdownファイルは、ユーザーが貢献者である場合にのみ機能する配布戦略だからだ。

これは多くのチームが二番目にぶつかる障害だ。ファイル自体は問題ないが、チーム外の誰もそれを読まない。これを解決するということは、項目が他の場所でレンダリングできるデータにならなければならないことを意味し、それはファイルをフォーマットするのとは異なる問題であり、チェンジログの例がリポジトリのファイルではなく公開されたチェンジログのページを集めている理由でもある。それらの項目を人々が戻ってくるものへと変える方法は、チェンジログページの作り方で扱っている。

それでも仕様を採用しよう。一晩分の時間はかかるが、二つ目の問題を扱いやすくし、これについて書かれた中で今も最良の一ページであり続けている。仕様どおりに組んだ完全なファイルはCHANGELOG.mdに何を書くかにある。

FAQ

Keep a Changelogは標準か? 広く採用されている慣習であり、標準化機関の仕様ではない。ツール(リリーススクリプト、リンター、パーサー)はその形式を十分な頻度で想定しているため、それに従うことで互換性を買うことができる。

Unreleasedセクションには何が入るか? マージされたが、まだ番号付きのリリースとして出荷されていない変更ごとの各項目。リリースが切られると、そのセクションはバージョンと日付に改名され、新しい空のUnreleasedセクションがその上に置かれる。

チェンジログはセマンティックバージョニングを使うべきか? Keep a Changelogはそれを推奨しているが要求はしていない。ライブラリやAPIはそこから恩恵を受ける。継続的にデプロイされるサービスは通常、日付で代替しており、その形式はそれを許容している。

セキュリティ修正は公開前にチェンジログに載せるべきか? 修正が出荷されたときに項目を追加し、オペレーターが行動できる程度の詳細を含め、それ以上は含めない。協調された開示日まで項目を遅らせることは普通だが、それを省略することは違う。


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

Changeloopの関連ページ: changelogの例, changelogツール比較

changeloop
ループを閉じるchangelogを作っているチームです。ユーザーが何かを求め、あなたのチームがそれを届け、求めた人がそれを知る。