チェンジログのファイル形式、JSONかYAMLか単なるMarkdownか
1分で読めます
ほとんどのチームはチェンジログをMarkdownファイルとして始める。それが最も抵抗の少ない道だからだ。プルリクエストのdiffで読め、何もレンダリングせずにGitHubで読め、READMEを書いたことのある誰にとっても馴染み深い。この選択は、人間以外の何か、ページ、ウィジェット、メールダイジェストがそのファイルを読む必要が出てくるまでうまく機能し、その時点で形式は無料でなくなる。チェンジログの自動化は構造的要件を一般的に扱う、タイプ、日付、本文、リンクだ。これはどのファイル形式が実際にその構造を提供し、それぞれにたどり着くのに何がかかるかについてのものだ。
単純なMarkdownチェンジログの何が問題なのか
何も問題ではない、何かがそれをフィールドに再度パースする必要が出てくるまでは。見出し、日付、その下の箇条書きリストは、人間にとっては読むのが取るに足らないことで、信頼性高くパースするのは本当に難しい。なぜならMarkdownにはスキーマがないからだ。日付は見出しにあるかもしれないし、最初の行に太字であるかもしれないし、古いエントリではまったく欠けているかもしれない。これらの変種のそれぞれが、人間は正しく読み、パーサーは読まない有効なMarkdownだ。Markdownチェンジログを自動化するチームは通常、エントリのフォーマットが少しでもずれた瞬間に壊れる、正規表現ベースの自作パーサーを書くことに終わる。これはよく起こる、書く時に一貫性を強制するものが何もないからだ。
構造化された形式が実際にもたらすものは何か
エントリが読まれる時に推測されるのではなく、書かれる時にチェックされる、すべてのエントリが同じ形を持つという保証だ。定義されたスキーマ、タイプ、日付、バージョン、対象読者、本文、リンクを持つJSONまたはYAMLファイルは、厳密なAPIレスポンスがそうするのとまったく同じように、必須フィールドが欠けていれば大声で失敗する。Markdownファイルは、正しいかどうかにかかわらず、そこにあるものを単にレンダリングするだけだ。この違いは、スクリプトがフィードをソートするために各エントリの日付を必要とし、エントリの半分がそれを異なる場所に保持している日まで見えない。
# CHANGELOG.yml
- date: 2026-09-05
type: breaking
version: v2
audience: api
body: "POST /invoices now rejects a currency mismatch instead of silently converting."
link: /blog/api-changelog/それは人間可読なファイルが消えなければならないという意味か
いいえ、そしてYAMLやJSONファイルに、人間がプルリクエストで読むものとしての二重の役割を果たさせようとすることは、通常逆方向の間違いだ。ネストされたJSONのdiffをレビューすることは、散文の一文をレビューすることより悪い。表現の誤りを捕まえるためにデータ構造を頭の中でパースしなければならないレビュアーは、やがて表現の誤りを捕まえるのをやめるレビュアーだ。二つの形式は共存できる。構造化データは自動化パイプラインが読む真実の源であり、生成されたMarkdownまたはHTMLのレンダリングは、手作業で横に維持されるのではなく、構造化ファイルから生成された、人間が実際にレビューし読むものだ。
| 形式 | そのまま人間可読か | カスタムコードなしで機械パース可能か | よくある失敗モード |
|---|---|---|---|
| Markdown | はい | いいえ | 一貫しないエントリ形式が単純なパーサーを壊す |
| JSON | 悪い | はい | 冗長；手動で無効なJSONに編集しやすい |
| YAML | まあまあ | はい | 空白に敏感；悪いインデントは大声ではなく静かなパースエラー |
どちらの構造化形式が実際に手動編集しやすいか、JSONかYAMLか
YAMLだ、ジェネレーターを介さず手動でエントリを書く誰にとっても。なぜならJSONが各文字列とネストされたオブジェクトに要求する引用符付けと括弧のマッチングを取り除くからだ。トレードオフは、YAMLの空白への敏感さが、JSONの括弧の不一致が通常しないやり方で静かに失敗することだ。JSONパーサーは不正な形式の入力を即座に拒否するが、YAMLパーサーは悪くインデントされたファイルを受け入れ、それを単に間違った構造にパースしてしまうことがある。これはより悪い失敗だ、それが起きたことを何も教えてくれないからだ。エントリが常にスクリプトによってのみ書かれるなら、このトレードオフはほぼ消え、JSONのより厳格なパースがより安全なデフォルトの選択になる。
チェンジログページは、それを供給するファイルとは別の独自の構造化形式を必要とするか
別のものではなく、異なる形でレンダリングされた同じものだ。チェンジログページは、JSONフィードとschema.orgマークアップを通じて、ページ自体を機械可読にする方法を扱っている。そのフィードは生成された出力であり、基礎となるファイルと同期を保つべき二番目の真実の源ではない。ソースファイルとページのフィードという二か所で構造化データを手動で維持することが、その二つが最終的にずれる理由だ。だからここで下されるファイル形式の決定は、ページ、ウィジェット、メールなど、後続のすべてがそこから生成される唯一のものであるべきで、手動でコピーされるべきではない。
既存のMarkdownチェンジログを構造化形式に変換する移行コストは価値があるか
通常、自動化が実際の目標になった時だけで、それ以前ではない。GitHubのREADMEにMarkdownファイルを公開している一人プロジェクトには実際の自動化の必要性がなく、それをYAMLに変換しても儀式以外何も買わない。この変換は、ページ、ダイジェストメール、公開フィードといった複数の下流の消費者が同じデータを読む必要が出てきた瞬間に、自分自身の元を取る。なぜならそれこそが、Markdownパーサーの不整合が、維持するのに面倒なだけの存在から、目に見えて間違った出力を生成し始める、まさにその地点だからだ。
FAQ
Markdownチェンジログは形式を完全に変えることなくパース可能にできるか? 部分的に、フロントマターで。各エントリの先頭にある小さなYAMLブロック（日付、タイプ、バージョン）を、散文のためのMarkdown本文の隣に置く。これはエントリ全体をJSONやYAMLに強制することなく、パーサーが必要とする構造化フィールドを得る方法であり、完全な移行にまだ準備ができていないチームにとって合理的な中間点だ。
ファイル形式はSEOやチェンジログページのランキングに影響するか? 直接的には影響しない。検索エンジンはレンダリングされたページを読むのであってソースファイルを読むのではないので、ファイル形式は検索エンジンにとって見えない。ページ自体にとって重要なのは、それ自体の権利として機械可読であるかどうかであり、それは何がそれを生成するかとは別の問題だ。
すべてのチェンジログエントリは同じファイルを通るべきか、それともタイプごとに複数のファイルに分割できるか? 一つのファイルの方が、エントリの量がdiffやレビューを不便にするまでは単純だ。年やカテゴリごとの分割は、一つのファイルのdiffが合理的にレビューするには大きすぎるようになった時点での合理的な安全弁だが、下流の何かが「すべてのエントリ」を一つのリストとして読める前に、マージのステップを追加する。
RSSに標準があるように、標準的なチェンジログファイル形式はあるか? 広く採用されているものはない。Keep a ChangelogはMarkdownの慣習を提案しており、いくつかのツールは独自の形式を持っている。changesetは、パッケージとバージョンの上げ幅を指定するYAMLフロントマター付きのMarkdownファイルで、上で説明したフロントマターのパターンそのものだ。これらのどれも、RSSリーダーが普遍的にRSSを理解するように、他のツールがそのまま読める形式ではない。
この記事の技術的な記述は第三者による確認を受けていません。誤りがあればお知らせください。修正します。