チェンジログとリリースノート、その違いはどこにあるのか

チェンジログとは、変わったことすべての継続的で累積的な記録であり、何かを探している人のために書かれる。リリースノートとは、一つのリリースについての選定されたメッセージであり、自分に関心があるかを判断しようとしている人のために書かれる。違いは書式ではなく読者にある。そしてほとんどのチームは両方を必要とする。一方は参照用に、もう一方は発表用に、同じ項目から導き出される。

多くのチームは偶然どちらか一方を持ち、もう一方は求められて持つことになる。開発者が出荷したものの記録を欲しがるからチェンジログから始める。数か月後、サポートの誰かが、四月から公開されている機能について顧客が知らなかったのはなぜかと尋ね、そこで初めてリリースノートが必要になる。

チェンジログとリリースノート、並べて比較する

チェンジログとは何か

チェンジログとは、変わったことの時系列的でほぼ完全な記録であり、最新のものが先頭にあり、各項目がタイプ分け（added、changed、deprecated、removed、fixed、security）され、日付が付いている。その読者はすでに関心があると決めている。彼らは何かを探している。いつ動作が変わったか、バグが修正されたか、どのバージョンでフラグが導入されたか。完全性がすべての価値であり、だからこそKeep a Changelogの慣習は、たった一ページのほとんどを構造に費やし、文章にはほとんど費やさない。

リリースノートとは何か

リリースノートとは、一つのリリースについての選定された、文章で書かれたメッセージだ。その読者はまだ何も決めていない。このリリースが自分に関係あるか、そして何か対応が必要かを判断しようとしている。選定がすべての価値だ。すべてを列挙するリリースノートは、段落付きのチェンジログにすぎず、何かを省略するチェンジログが読者を裏切るのと同じ方法で、その読者を裏切る。リリースノートの書き方は、選定と表現の仕方についての記事だ。

チェンジログとリリースノートの両方が必要か

二つの読者層が異なるものを求め始めた時点で、両方が必要になる。それまでは、両方の役割を果たす一つの成果物で正しい。小さなチームは、各項目の先頭に短い段落を添えた一つの /changelog ページを公開し、しばらくの間はそれが、修正を探す開発者と、ニュースを見出す顧客の両方に等しく役立つ。早すぎる分割は、維持すべきものを二つ与え、そのどちらか一方は腐っていく。

分割の価値が出てくるのは、次のことが起き始めたときだ。

• チェンジログの項目が、開発者が読み飛ばす説明的な段落に膨れ上がっている。
• あるいはその逆。リリース発表が依存関係の更新を列挙し始めている。
• サポートが項目をメールにコピーし、途中で書き直している。
• 誰かが「破壊的変更だけ」を求めるが、それをフィルタリングできない。

最後のものが本当のサインだ。すべてを読まなければ「自分に関係ある変更は何か」に誰も答えられないなら、二つの仕事を下手にこなす一つの成果物を持っているということだ。

一つのソース、二つのビュー

間違いは、それらを二つの文書として扱うことだ。それらは同じ変更の集合に対する二つのビューにすぎない。

チェンジログは進行に合わせて書く。重要な変更ごとに一項目、それぞれ何であるかを示すラベルを付ける。fixed、added、changed、removed、deprecated、security。一つ書くことが決断にならないくらい、項目を短く保つ。そしてリリースの時点で、リリースノートは選定と書き直しになる。人にとって重要な項目を取り、それが可能にすることでグループ化し、理由を上に置く。

これには実際的な帰結がある。チェンジログがソースであるなら、それは手動で維持されるページではなく、構造化されたデータである必要がある。項目にはタイプ、日付、バージョン、そして誰のためのものかを示す方法が必要だ。それさえあれば、公開ページ、アプリ内ウィジェット、RSSまたはJSONフィードはすべて一つのものの三つの表示にすぎず、顧客に届くまでの間に誰も何も書き直す必要がない。リリースノートのメールも、メールを送っているツールが何であれ、そこから同じ項目を引用できる。チェンジログの自動化は、これらのステップのどれを機械が所有すべきかについての記事だ。それがチェンジログをページではなくフィードとして扱うことの、まさにすべての論拠だ。これはまた、完全に透明に言えば、私たちが構築しているものでもある。だからこれを中立的な調査ではなく、利害関係として読んでほしい。

どちらか一方にしか時間がないなら

チェンジログを書く。項目あたりの費用が安く、書いたその日から役に立ち、リリースノートは後からそこから導出できる。逆は成り立たない。十二通の発表メールから一年分の変更を再構築することはできず、人々はそれをあなたに求めてくる。

導出が可能であり続けるよう、固定された形式で保つ。私たちのチェンジログの例のページは、それをうまくやっているチームの項目を集めており、リリースノートのテンプレートは、項目の集合を送る価値のあるものへ変える際に使う形式だ。

命名についての注意

これらはどれも標準化されておらず、「リリースノート」が継続的なリストに使われ、「チェンジログ」が四半期ごとの発表に使われているのを見つけることになる。言葉について争うのは価値がない。あなたのそれぞれの成果物がどちらの役割を果たしているかを決め、あなたのチームがすでに呼んでいる名前で呼び、どちらも密かに両方をこなしていないことを確認する。

結果がどの表面に着地するかは別の決定であり、チェンジログページの作り方で扱っている。

FAQ

チェンジログとリリースノートは同じものか? 違う。チェンジログは何かを探している人が読む完全な記録であり、リリースノートは関心があるか判断する人が読む選定された発表だ。同じ変更が両方に現れるが、それぞれの読者向けに異なる表現がされる。

リリースノートはチェンジログから生成できるか? できる、そしてそれが正しい方向だ。人にとって重要な項目を選び、結果でグループ化し、見出しを書き直す。逆に発表からチェンジログを再構築することは、発表が省略したすべてを失う。

チェンジログはどこに置くべきか? リポジトリなしで読者が到達できる、永続的でリンク可能などこかに。/changelog ページ、ドキュメントサイト、あるいは複数の場所でレンダリングされるフィード。CHANGELOG.md だけでは貢献者には届くが、顧客には届かない。

チェンジログに内部の変更を含めるべきか? 含めるべきだ。末尾に一行ずつ。チェンジログは完全な記録だ。リリースノートにも短い最後のセクションとして残してよいが、読者が気づく変更を先に置くことが条件だ。

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

changeloopの関連ページ： changelogの例, リリースノートのテンプレート