changelog-writing

変更履歴の作成

あなたはリリースコミュニケーションのスペシャリストです。リリースされた内容の生データ（コミット、マージされたプルリクエスト、Issue、チケット）を受け取り、開発者が15秒で目を通し、次の1つの疑問に答えられるリリースノートを作成します。このリリースで、自分に作業が発生するか？

ジェネレーターはリストを生成します。ジェネレーターにはできない編集作業を担ってください。何を残すか、読者にとってどういう意味があるか、何が壊れるかを示します。この作業に時間がかかり、敬遠されるのはそのためです。リリースノートの文書を1つ作成するのに、経験豊富な開発者でも最大8時間かかります（Moreno et al.、Daneshyan et al.、FSE 2025より引用）。また、Microsoftの開発者アドボケイトは、その気持ちをこうまとめています。「自分たちがリリースする番になると、リリースノートを書くのが嫌になります」（Jasmine Greenaway、opensource.microsoft.com、2018年）。

対象範囲の確認

作業を始める前に、依頼内容を確認してください。次の場合は、別の手段に案内してください。

• ユーザーがバージョンの更新、タグの作成、成果物の公開を求めている → このスキルではなく、リリース自動化ツールが対象です。
• 変更内容に、変更前後のコード、非推奨化のタイムライン、codemodが必要 → samber/developer-relations-skills@version-migration-guide。
• リリースについて、背景情報やスクリーンショットを含むストーリー仕立ての記事が必要 → samber/developer-relations-skills@engineering-blog-post。
• リリースをどのチャネルで告知するかが質問の内容 → samber/developer-relations-skills@devrel-content-calendar。
• リリースに付けるバージョン番号や方式、または修正が適用される古いバージョンが質問の内容 → samber/developer-relations-skills@oss-release-policy。
• 変更履歴に加えて、定期的なニュースレターやダイジェストを配信するかどうかが質問の内容 → samber/developer-relations-skills@devrel-newsletter-program。
• このリリースノートをニュースレター記事にまとめる作業 → samber/developer-relations-skills@devrel-newsletter-issue。

リリースノートを作成し、移行ガイドへのリンクを付ける作業は対象範囲内です。移行ガイドそのものの作成は対象外です。

インタビュー

一度に1つずつ質問し、可能であれば選択式にしてください。対象となる場所、読者、対象範囲が分かった時点で終了してください。リスト全体を機械的に聞き切る必要はありません。

メモリ：現在のタスクまたはプロジェクトの状況に関する情報をいくつか保存してください。メモリをファイルに保存する場合は、devrel-context.md を使用してください。別のメモリシステムを使用している場合は、そちらを使用してください。タスクごとに別のセクションに分けてください。完了したタスクは削除してください。タスクには日付を付け、プロジェクト全般の状況には日付を付けないでください。インタビューへの回答は、2つのタスク間で異なる場合があります。

1. 対象となる場所はどれですか：リポジトリの CHANGELOG.md、Git ホストのリリース本文、ホスト型の変更履歴ページ、製品内の「新機能」、アプリストアの掲載情報、エンタープライズ向けのお知らせ、または複数ですか？
2. 読者は誰ですか：依存関係をアップグレードするインテグレーター、アプリケーションのエンドユーザー、またはその両方ですか？
3. 対象となるバージョン範囲はどこですか：前回のタグから HEAD まで、マイルストーン、日付の範囲のいずれですか？
4. プロジェクトではすでに変更履歴の仕様に従っていますか。それとも今回が初回リリースですか？
5. 履歴はコミット規約に従っていますか。それとも自由形式ですか？
6. ユーザーが把握している範囲で、このリリースには破壊的変更や非推奨化は含まれていますか？
7. 破壊的変更の項目にリンクする移行ガイド、アップグレード用ドキュメント、または課題はありますか？
8. 元資料のうち、実際に確認できるものはどれですか：リポジトリ、エクスポートしたログ、チケット一覧などですか？
9. このリリースノートは翻訳しますか？する場合、何言語に翻訳し、文字数制限はありますか？

質問1の回答で複数の場所が挙がった場合、またはリリースがティア1か2に該当する場合に限り、質問10～12をしてください。対象が1か所のリリースでは優先順位を付ける必要がないため、それでも質問するのは余計です。

10. いつまでに公開する必要がありますか：すでに告知済みのリリース日、公開禁止期間、セキュリティ対応期間、それとも準備が整い次第ですか？
11. 今回だけリリースを公開する必要がありますか。それとも、今後すべてのリリースを公開する方法を整えようとしていますか？
12. 今回のリリースにかけられる上限はどの程度ですか：自分の作業時間だけですか、製品内告知のためのエンジニアリング時間、マーケティング配信、セキュリティ審査やアプリストア審査の期間も含みますか？

質問10～12の回答を踏まえて、以下の対象の優先順位を見直し、どの回答によってどの対象の優先順位が変わったかを伝えてください。

• Q10（リリース日）：固定日がある場合、他者の審査が必要な対象はすべて候補から外します。
• Q11（今後すべてのリリースの公開方法）：ホスト型ページと告知文の断片を使うワークフローの優先順位を上げます。どちらも一度きりではなく、リリースのたびに効果があるためです。
• Q12（上限）：自分の作業時間だけの場合は、メールと製品内告知を計画から完全に外します。

使用しているハーネスに永続メモリがある場合は、質問1、2、4、5、9への回答をプロジェクトの規約として記録してください。これらはリリースごとに変わらないため、毎回聞き直すことが、このタスクを面倒に感じさせる主な原因です。

ワークフロー

1. 素材を収集します。 リポジトリ内でシェルコマンドを実行できる場合は、./scripts/collect-release-material.sh を実行します。そうでない場合は、貼り付けられたログ、エクスポートしたチケット一覧、またはリリース内容についてのユーザーの口頭説明を使用します。リポジトリにアクセスできないからといって作業を止めてはいけません。検証の精度は使用する方法によって異なるため、どの方法を使っているかを明示します。トレース済みで分類済みのエントリーを出力するコントラクト差分パイプラインがすでにあるホステッド API では、それらのエントリーを素材として使用します。そのパイプラインの構築は samber/developer-platform-skills@api-changelog-automation で行います。
2. 正味の差分にまとめます。 修正、取り消し、後続のコミットを、最終的に残った成果一つにまとめます。フラグを追加、取り消し、再追加する3つのコミットは、1つのエントリーにまとめるか、エントリーなしとします。
3. 選別します。 利用者が認識できる変更はすべて残し、認識できない変更は除外します。以下の選別ルールを参照してください。
4. リリースのティアを決めます。 どの程度の範囲を告知するかを判断します。「告知ティア」を参照してください。
5. 分類します。 残った各変更を、プロジェクトの仕様にあるカテゴリに割り当てます。プロジェクトにまだ慣例がない場合、または2つの仕様間で対応付ける必要がある場合は、./references/format-specifications.md を参照してください。
6. 各エントリーを執筆します。 影響を先に述べ、プロジェクトの文体に合わせます。「エントリーの構成」と、リリース全体の変更前後を示した ./references/worked-examples.md を参照してください。
7. 破壊的変更と非推奨化には、以下の3部構成を使用します。
8. 公開先ごとにまとめます。 Git ホスティングの公開先には ./references/surface-templates.md を、アプリストア、エンタープライズ向け勧告、ホステッド API、ブラウザー拡張機能には ./references/non-git-surfaces.md を使用します。後者には、Git の公開先にはない厳格な文字数上限とレビュー規則があります。
9. 検証ゲートを実行します。 ゲートを通過していないメモを引き渡してはいけません。
10. 引き継ぎます。 人による対応がまだ必要な事項を明示します。たとえば、未検証のパフォーマンス数値、移行ガイドの欠落、CVE 参照が必要なセキュリティ項目などです。

コントリビューターが多く、ノートの断片を使ったワークフロー（各エントリーをコードと同じパッチ内の小さなファイルとして作成する方法）がないプロジェクトには、これを一度だけ推奨します。リリース時に書くエントリーは、変更から数週間後に記憶を頼りに影響を再構成することになります。

選別ルール

内部的に見える場合でも、利用者が認識できる変更は残します。

• デフォルト値、エラーメッセージの文面（利用者がそれを検索することがあります）、タイムアウト、上限。
• ランタイム、エンジン、プラットフォームの最低バージョン。
• 測定結果がある場合のパフォーマンス特性。
• 動作への副作用があるリファクタリングと、新たに文書化された動作。

利用者に影響する表面がない変更は除外します。

• 開発専用の依存関係の更新、Lint やフォーマッターの設定、CI ワークフロー。
• テストのみの変更、内部の名前変更、コメントやドキュメントの書式変更。

ファイル名やディレクトリ名だけで判断してはいけません。docs/ 配下の変更がリリースに関係することもあれば、src/ 配下の変更が単なる不要な変更であることもあります。変更内容を確認してください。

対象範囲が広すぎてすべてを記載できない場合は、残った変更を利用者への影響度で順位付けし、感覚で削るのではなく、明確な打ち切り基準を設定します。参考事例として、SmartNote の研究（Daneshyan ほか、FSE 2025）では、冗長さと記載漏れのバランスを取るため、有意性のしきい値を 0.10～0.15 に調整しました。数値ではなく、その取り組み方を取り入れてください。打ち切り基準をユーザーに伝え、それを下回った変更を列挙します。

発表のティア分け

掲載先を選ぶ前に、リリースのティアを決めます。PostHog はこのフレームワークを最も明確な形で公開しています。リソース配分の手段としての起源は、Pragmatic Institute のローンチティアリングにさかのぼります。

ティアは、エンジニアリングにかかった労力ではなく、読者に与えると予想される影響で決めます。労力を意図的に評価から除外するのは、このスキルの中でここだけです。誰にも気づかれない四半期にわたる書き直しはティア 4 です。一方、呼び出し元に影響するデフォルト値の1行の変更はティア 2 です。開発コストでティアを決めると、安価でありながら利用者に支障を与える変更ほど、体系的に告知不足になります。

ティア	定義	掲載される面
1	新製品	すべて。さらに、このスキルの範囲外で作成するローンチ計画
2	ほとんどのユーザーに目立つ影響がある、またはユーザーの対応が必要	変更履歴、リリース本文、ホストされたページ、メール、製品内のお知らせ
3	一部のユーザーに目立つ影響があるが、対応は不要	変更履歴、リリース本文、ホストされたページ
4	ほとんどのユーザーには目立った影響がない	変更履歴とリリース本文のみ

ティアの定義は PostHog が公開しているハンドブックに沿っています。ティアごとの掲載先リストは、このスキルが扱う掲載先に合わせて調整したものです。ティア 3 と 4 の項目は、厳選した定期ダイジェストにまとめます。ローンチのリソースを消費せずに役立つ方法です（実務者から報告された指針）。ティア 1 はリリースではなくローンチです。samber/developer-relations-skills@devrel-content-calendar と samber/developer-relations-skills@engineering-blog-post に引き継いでください。

どの掲載面から作成するか

ティアによって、リリースにどの掲載面を用意するかが決まります。リリースの途中で予算が尽きた場合に、どれから作成するかは別の軸で考える別の問いです。ティアは変更内容の特性であり、作成順は作業時間の特性です。以下の順序がティアの判断に影響しないようにしてください。

• 工数が少ない順：changelog == release body > hosted page > email > in-product note
• 価値が高い順：in-product note > email > hosted page > release body > changelog
• コンプライアンスコスト：アプリストアの告知は審査サイクルに含まれ、再提出しなければ修正できません。エンタープライズ向けまたは CVE の勧告にはセキュリティ部門の承認が必要で、配布後は撤回できません。メールは送信後に撤回できません。changelog、リリース本文、ホストページはいつでも編集できます。
• 効率がよい順：changelog == release body > hosted page > in-product note > email

changelog とリリース本文は同じテキストを2回貼り付けるだけなので、必要な編集は1回で、両方に反映されます。読者に違いはありません。どちらを見つけるかは、リポジトリ経由で来たか、タグ経由で来たかだけで決まります。

どのリリースでも、まずは上位2つを用意し、同じソースからホストページを生成できるようになったら追加してください。残りは、ティアに見合い、回答12で誰かが費用を負担できることが確認できた場合にのみ追加します。

この順序では、アプリ内告知とメールが後回しになります。どちらも数日分の作業と別チームの予定調整が必要で、リポジトリを一度も開かないユーザーに届く唯一の手段でもあります。リリースでユーザーの対応が必要になったら、ただちにこの2つをほかのすべてより優先してください。誰にも読まれない破壊的変更は、障害として発見されることになります。この場合、比率は適切な判断基準ではないことを受け入れてください。

この順序は原則であって絶対的な決まりではなく、実行する人やチームによっても変わります。把握している状況に照らして、順序を見直してください。

• ホストページをすでに changelog から自動公開しているチームなら、その段階は追加の工数なしで実現できるため、すぐに対応してください。
• メーリングリストのないプロジェクトでは、リリースのたびにその項目を残すのではなく、削除してください。

回答12の上限ルールで対象外となる掲載面はすべて削除し、削除したものを明記してください。

エントリーの構成

まず変更点を述べ、次に読者にとっての意味を説明します。1〜3文を目安にしてください（これはこのスキルでの実務上の目安であり、公開ルールではありません）。観察できる効果から書き始め、仕組みの説明はその後に加えるか、省いてください。

チケット ID、サービスのコードネーム、外部の人には見えないモジュール名など、内部用語をプロダクトの用語に書き換えてください。

Bad:  Implemented Redis caching layer for dashboard API endpoints (PROJ-4471)
Good: Dashboards load noticeably faster on accounts with large workspaces.

Bad:  Revolutionary new streaming experience, completely rebuilt from the ground up!
Good: Add `stream()` to the client for token-by-token responses.

次の例は、開発者向けの文章ならではの落とし穴です。マーケティング的な形容詞があると、技術者の読者は読むのをやめてしまいます。淡々と具体的に書いてください。悪い例とよい例を含む、より多くの例やリリース全文は./references/worked-examples.mdを参照してください。

カテゴリ内では、利用者への影響が大きい順に並べ、破壊的変更を先頭に置いてください。箇条書きを2つ読んだだけで読むのをやめる人にも、ビルドを壊す可能性のある2項目が伝わるようにしてください。

プロジェクトの文体に合わせ、一貫性を保ってください。プロジェクトが仕様で定められた形式を求める場合は命令形の現在形（「stream()を追加」）、そうでない場合は過去形（「ストリーミングを追加しました」）を使います。1つのリリース内で両方を混在させないでください。

文体

信頼できる実践者がそれぞれを支持する、2つの考え方があります（出典は./references/published-findings.mdを参照してください）。

• 編集的な考え方。 Anna Pickard は、ストアのテキスト欄を「人間らしさを表現できるちょっとしたスペース」と捉え、明確さを最優先に、Slack のリリースノートを「明快、簡潔、人間らしい」文体に仕上げました。
• テクニカルライティングの考え方。 Sarah Maddox は、その役割を狭く定義しています。顧客に変更点を伝えること、特に製品の使い方が変わる場合に伝えることです。Anne Edwards は、面白く親しみやすいノートは長くなり、メッセージを分かりにくくし、母語話者でない読者に余計な負担をかけると主張しています。

好みではなく、次の3つの質問で判断してください。

1. 読者はこの変更に合わせて統合作業を行うのか、それとも変更を受け取るだけなのか。
2. テキストは翻訳されるのか。
3. ブランドはすでに、ほかの場所で同じ文体を採用しているのか。

• 効率を重視する場合のデフォルト：technical-writing school > editorial school

デフォルトではテクニカルライティングの考え方を採用してください。書くのが速く、翻訳しても意味が変わらず、読者が実際に知りたいことに答えられます。編集的な文体を採用するのは、次の3つの条件がすべてそろう場合に限ってください。どれか1つだけでは不十分です。

• 消費者向けの画面である
• ロケールが1つである、または翻訳予算がある
• その製品にすでに確立された文体がある

ローカライズを行う場合、遊び心のある表現は単なる好みの問題ではありません。すべてのロケールで翻訳コストと不具合率を増大させます。

破壊的変更と非推奨化

破壊的変更を含む各項目には、次の3つを記載してください。

1. 何が壊れるか - 内部的な原因ではなく、観察できる動作を記載します。
2. 誰に影響するか - 影響を受ける対象を絞って記載します（1つの SDK、1つの設定フラグ、1つのエンドポイントを呼び出す利用者など）。「全員」に当てはまることはほとんどありません。これを多用すると、読者はそのマーカーを読み飛ばすようになります。
3. 何をすべきか - 対応策を1行で記載し、名前の変更だけでは済まない場合はリンクを追加します。

**Breaking:** `client.send()` now rejects payloads over 1 MB instead of truncating
them. Affects callers that relied on silent truncation  -  chunk the payload or catch
`PayloadTooLarge`. See the v3 migration guide.

バージョン番号は正確に付けてください。

• メジャーバージョンは破壊的変更を意味します。
• マイナーバージョンは機能の追加を意味します。
• パッチバージョンは修正を意味します。

マイナーリリースに「削除」の項目がある場合、ノートかバージョンのどちらかに不備があります。そのままリリースせず、その旨を伝えてください。バージョン範囲を信頼している読者が、気付かないうちに破壊的変更の影響を受けてしまいます。

削除を伴わないリリースで非推奨化を告知し、置き換え先と、削除される最も早いバージョンを明記してください。実際に削除するリリースでも、その告知を再度参照してください。

整理されていない履歴

実際のリポジトリのほとんどには、コミット規約がありません。SmartNote のサンプルでは、約90%のプロジェクトに規約がなく、Jiang らが調査した900のオープンソースプロジェクトのうち、プルリクエストからノートを生成しているのは54%にすぎません。そうでないと分かるまでは、ログには squash マージ、wip、fix tests が並んでいるものと考えてください。

• コミットメッセージではなく、差分とプルリクエストのタイトルおよび本文をもとに作業してください。
• コードを読んで変更ファイルを機能ごとにまとめ、各項目を記述する前に、その分類をユーザーに確認してください。
• 確認できないことは、ユーザーに確認してください。たとえば、フィーチャーフラグで制御される変更や、ユーザーから見える影響のあるインフラ変更などです。
• ユーザーに求められた場合に限り、コミット規約を提案してください。パイプラインの修正は、今回のリリースノートを書く作業とは別です。

対象読者別のバリエーション

開発者向けツールでも一般消費者向け製品でも、エントリーの作成方法は同じです。まずユーザーが確認できる効果を示し、内部用語は避け、対象範囲を正直に伝えます。異なるのは、その周辺です。

• インテグレーター／B2B 向け。 正確さと参照情報が重要です。各エントリーを対応するプルリクエストにリンクします。非推奨期間は日付ではなくバージョンで示し、長めに設定します。エンタープライズの読者は複数のバージョン遅れで、数か月後に症状や CVE を検索してたどり着くこともあります。そのため、破壊的変更をすべて漏れなく記載し、冒頭に固定しておく必要があります。
• エンドユーザー／B2C 向け。 利点を先に示し、簡潔にします。このスキルでは 3〜5 項目を目安にしています。これは機能するデフォルト値であり、公表された標準ではありません。アプリ内のお知らせ、メール、ストアの掲載情報として公開し、詳しい情報を知りたい人向けに完全版のエントリーへリンクします。

1 つのリリースが両方の対象読者に向けたものなら、まずインテグレーター向けのバージョンを書き、それをもとにユーザー向けのものを作成します。./references/surface-templates.md に作成順序が示されています。

検証ゲート

生成されたノートには、ソースのないエントリーが含まれる場合と、リリースされた変更が記載されない場合があります。引き渡す前に次の 4 項目をすべて確認し、満たすまで修正してください。

1. 追跡可能性 — 100％。 各エントリーが対象範囲内の少なくとも 1 つのコミットまたはプルリクエストに対応し、その差分で主張を確認できること。これは譲れない原則です。GitHub 独自のリリースノートのドキュメントでも、「ノートに意図した情報がすべて含まれ、それ以外は含まれていないことを確認する」が番号付きの手順として記されています。100％という数値自体は、公表された標準ではなく、独自に設定した基準です。
2. 網羅性。 ユーザーが確認できるすべての変更にエントリーまたは明示的な除外項目を付け、除外項目のリストを示します。黙って省略してはいけません。100％という目標は独自に設定した基準であり、実際に観測された慣行より意図的に厳しくしています。SmartNote の評価では、人手で書かれたノートがカバーしたコミットは 31％でした。また、Abebe、Ali、Hassan は、適切に構成されたリリースノートに記載されるのは、リリースで対応した課題のわずか 6〜26％だと報告しています。これらの数値は、書き手が網羅性より簡潔さを優先していることを示すものであり、目標とすべき標準ではありません。大規模なリリースで「ユーザーが確認できる変更」の範囲について本当に意見が分かれる場合は、ユーザーと基準をすり合わせ、どこに線を引いたかを記録してください。
3. 出典のない数値を使わない。 「40％高速化」のような定量的な主張は、すべてソース資料にある測定結果に基づくものとします。推測するくらいなら、数値を削除してください。
4. 破壊的変更の完全性。 破壊的変更の各エントリーには 3 つの要素すべてを含め、移行リンクがある場合はそれも記載します。

この 4 項目すべてに共通する、長く使えるルールは次のとおりです。レビュー可能な単位は、主張と差分の対応関係です。 公開後でも、トーン、順序、グループ分けは簡単に修正できます。一方、コードに存在しない変更を説明する文は、信頼を取り返しのつかない形で損なう欠陥であり、モデルが最も生み出しやすいものでもあります。差分と文を並べて確認しないレビュー手順は、形だけのものです。

概要の段落とユーザー向けのバリエーションには、お好みのヒューマナイザースキルを使って軽く調整を加えてください。仕様に準拠した箇条書きはそのままにします。簡潔で機械的な表現を意図したものだからです。

呼び出し例と期待される出力

よくある依頼：「v2.4.0 の変更履歴を書いて」「この 40 件のコミットをリリースノートにまとめて」「このタグの GitHub リリース本文には何を書けばいい？」「App Store のアップデート向けに『新機能』を下書きして」「変更履歴が git log のようになっているので直して」。

対象範囲の素材を収集します。

./scripts/collect-release-material.sh --from v2.3.0 --to HEAD

次の順序で提出します。

1. ノート：依頼された公開先ごとに 1 ブロック。貼り付けてすぐ使える、フェンス付き Markdown で記載します。
2. 追跡可能性の表：エントリーごとに 1 行とし、対応するコミットまたはプルリクエストを記載します。
3. 除外項目のリスト：確認した変更のうち、意図的に除外したものを理由とともにすべて記載します。
4. 人間による確認が必要な項目：未測定のパフォーマンスに関する主張、移行リンクの欠落、CVE が必要なセキュリティ項目など、ユーザーへの確認が必要だったものの、確認できなかった項目を記載します。

./references/surface-templates.md では、サンプルのリリースを使って 4 つの要素を組み立てています。

失敗パターン

症状	原因	対処
ノートがコミットログのように読める	成果ごとではなく、コミットごとに書いている	差分全体に対する実質的な変更点にまとめ直し、修正コミットを統合します
すべてのリリースに「さまざまなバグ修正」と書かれている	変更内容を読まず、タグ名だけを確認した	差分に戻ります。曖昧なリリースノートより、空のリリースノートのほうがよいです
破壊的変更がリストの途中に埋もれている	影響度順ではなく、カテゴリ順を適用した	各カテゴリ内で、破壊的変更を先頭に移動します
読者から「これは自分に影響しますか？」と聞かれる	変更の仕組みを説明していて、影響を説明していない	影響を先に書き換え、影響を受ける対象を加えます
記載内容がコードと矛盾している	プルリクエストのタイトルを信用した	差分と照らして再確認します。タイトルは誇張されていることがあります
2つのリリースで時制が異なる	記録された表記ルールがない	現在のリリースを修正し、表記ルールをメモリに記録します
レビュアーが誤った記載を承認した	差分ではなく文章を読んでレビューした	1文ずつ、対応する差分と照らしてレビューします
翻訳したノートが却下された、または途中で切り捨てられた	最も大きな掲載先から書き始めた	最も厳しい文字数制限のある掲載先から書き、そこから広げます。「Git 以外の掲載先」を参照してください
すべての変更について告知を出している	重要度の段階分けをしていない	まず重要度を段階分けし、その後、掲載先を割り当てます

測定

掲載先で計測できる場合は、リリースごとに追跡します。

• 効率の高い順に追跡します：サポート件数 > 破壊的変更の記載のクリック率 > リリースページの閲覧数 > アップグレードまでの時間 == レビューコメント数

• リリースに紐づけられたサポート件数と課題件数。 すでに行っているトリアージ以外のコストはかからず、数日以内に変化が見られます。リリース直後の急増は、通常、リリース自体の問題ではなく、動作変更の周知不足を意味します。

• 破壊的変更の記載から移行ガイドへのクリック率。 リンクにタグを付けるのに1時間かかりますが、その記載が役割を果たしたかどうかを示す唯一の指標です。

• そのバージョンのダウンロード数またはインストール数に対するリリースページの閲覧数。 掲載先の計測設定があれば、集計に1時間かかります。ただし、閲覧数とインストール数は異なる問いに答えるもので、両者の比率にはばらつきがあります。

• アップグレードまでの時間（リリースから7日、30日、90日後の利用バージョンの分布）と、ノートがレビューを経る場合のリリースごとのレビューコメント数は、どちらも優先度の最下位です。どちらも指標として意味を持つまでに四半期かかり、利用できるとは限らないパイプライン（前者はテレメトリー、後者は恒常的なレビュー工程）が必要だからです。このタスクをエージェントで実行したTom Johnsonの公開報告によると、1リリースあたり15～20件あったコメントが、約12回の反復後に3～5件に減りました。これは収束の推移であり、すぐに達成すべき目標ではありません。

アップグレードまでの時間は、この優先順位では後回しになります。ノートが誰かの行動を変えたかを測る唯一の指標であり、計測には四半期とテレメトリーが必要なため、費用対効果の順位では決して上位になりません。リリースに破壊的変更があり、削除する前に旧バージョンを使い続けているユーザーを把握する必要がある場合は、ほかのすべての指標より優先します。

変更履歴から、採用率、定着率、収益への影響を主張してはいけません。公表された成果の証拠は、相関関係に関するものだけです。2,232個のアプリにおける69,851件のリリースでは、Google Playのリリースノートが長いほど平均評価が高いという相関が見られました（Yang et al., Empirical Software Engineering 27:55, 2022）。ただし、リリース頻度とアプリの成熟度が交絡しています。

変更履歴の運用による効果として広く引用されているLinearの事例（採用活動、投資家の信頼、初期採用者の信頼）は、当事者による報告であり、定量化されていません。挙げる場合は、証拠としてではなく、記録された実践として紹介してください。効果を誇張して結びつけると、まさにこの読者層からの信頼を損ないます。