ChangeLogとは、オープンソースプロジェクトで、バージョンごとにどのような新機能が追加されたか、どのような機能が変更されたのか等を説明するテキストファイルのこと。現状、特に書き方に決まりはなく、プロジェクトごとに自由な形式で書かれることが多いファイルです。
「Keep a CHANGELOG」はそんなChangeLogをより分かりやすく役に立つ形式で記述するための方法をまとめたドキュメントです。ファイルのフォーマットから、どのような事を書けばよいのかといった内容に関することまで事細かにまとめられています。
ChangeLogはかくあるべし
このドキュメントでは、以下のChangeLogが良いものであるとされています。
- 機械のためではなく、人間のためのものなので、読みやすさはとても重要。
- 任意のセクションへのリンクが簡単であること(このためMarkdownはプレインテキストを超える)。
- リリースは逆年代順(新しいのが先頭)。
- 日付はYYYY-MM-DD形式で。
- プロジェクトがSemantic Versioningに従っているか明記する。
- それぞれのバージョンは以下のようにすべし:
- リリース日は上記フォーマットで。
- 変更をプロジェクトをプロジェクトにとって影響のある、以下の順に記述する。
- Added: 新機能。
- Changed: 既存機能の変更。
- Deprecated: 今後のリリースで削除されるもの。
- Removed: 今回のリリースで削除されたDeprecatedな機能。
- Fixed: バグの修正。
- Security: 脆弱性に関するもの。
その他、最小限の労力でChangeLogを保守するために、"Unreleased"セクションを最上部に保持し、ユーザーが次回どのような変更が行われるのか分かりやすくするとともに、リリース時は、Unreleasedをバージョンナンバーに変更するだけで済むようにするといった提案なども行われています。
この他にも多くの指針が示されているので詳しくは原文を参照してください。またこのスタイルガイドに従った実際のCHANGELOG.mdも公開されています。
まとめ
Hacker Newsでは、「標準のChangeLogフォーマットが存在しない」とする主張に対し、GNUのスタイルガイドが存在しているという反論が行われていますが、GNUのスタイルガイドには、多くのオープンソースプロジェクトで使われておらず、また(gitのlogを確認すればわかるような)、細かい変更点に注目しすぎているという問題があるようです。
Keep a CHANGELOGは、Markdown形式で現代的なChangeLogを記述するための指針として参考となるドキュメントといえるかもしれません。よりよいChangeLogを書きたい開発社の方は参考にしてみてはいかがでしょうか。
