Keep a Changelog、実際に導入してみて分かったこと
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のどの部分が省略されるか
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は、これが依拠する二層構造と、どのコミットタイプが上記の六つのカテゴリーのどれに対応するかを扱っている。私たちのチェンジログツールのまとめは、収集の半分について何が存在するかをカバーしている。
Keep a Changelogはどこで十分でなくなるか
配布のところで止まる。Keep a Changelogは「このファイルはどう見えるべきか」への良い答えだ。「私たちのユーザーは何が変わったかをどうやって知るのか」への答えではない。リポジトリ内のMarkdownファイルは、ユーザーが貢献者である場合にのみ機能する配布戦略だからだ。
これは多くのチームが二番目にぶつかる障害だ。ファイル自体は問題ないが、チーム外の誰もそれを読まない。これを解決するということは、項目が他の場所でレンダリングできるデータにならなければならないことを意味し、それはファイルをフォーマットするのとは異なる問題であり、チェンジログの例がリポジトリのファイルではなく公開されたチェンジログのページを集めている理由でもある。それらの項目を人々が戻ってくるものへと変える方法は、チェンジログページの作り方で扱っている。
それでも仕様を採用しよう。一晩分の時間はかかるが、二つ目の問題を扱いやすくし、これについて書かれた中で今も最良の一ページであり続けている。
FAQ
Keep a Changelogは標準か? 広く採用されている慣習であり、標準化機関の仕様ではない。ツール（リリーススクリプト、リンター、パーサー）はその形式を十分な頻度で想定しているため、それに従うことで互換性を買うことができる。
Unreleasedセクションには何が入るか? マージされたが、まだ番号付きのリリースとして出荷されていない変更ごとの各項目。リリースが切られると、そのセクションはバージョンと日付に改名され、新しい空のUnreleasedセクションがその上に置かれる。
チェンジログはセマンティックバージョニングを使うべきか? Keep a Changelogはそれを推奨しているが要求はしていない。ライブラリやAPIはそこから恩恵を受ける。継続的にデプロイされるサービスは通常、日付で代替しており、その形式はそれを許容している。
セキュリティ修正は公開前にチェンジログに載せるべきか? 修正が出荷されたときに項目を追加し、オペレーターが行動できる程度の詳細を含め、それ以上は含めない。協調された開示日まで項目を遅らせることは普通だが、それを省略することは違う。
この記事の技術的な記述は第三者による確認を受けていません。誤りがあればお知らせください。修正します。