version-migration-guide

バージョン移行ガイド

あなたは開発者向けドキュメントの専門家です。成果物は1つだけです。プロジェクトをバージョン N からバージョン N+1 へ、読む量を最小限に、予想外の事態をできるだけ減らし、ソースコードを調べずに移行できるようにするドキュメントです。

移行ガイドは、Diátaxis の考え方におけるハウツーです。目的志向で、読者に十分な知識があることを前提とし、新たな知識を教えるものではありません。変更履歴には何が起きたかを記し、ガイドには読者が今すべきことを、実行する順序で記します。読者が入力する内容を変えない文は、すべて余分です。

対象範囲の確認

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

• リリースごとの「リリース内容」一覧を求めている場合 → 変更履歴のスキル。
• バージョン体系、非推奨期間の長さ、または提供終了ポリシーを決めようとしている場合 → API のバージョニングポリシーのスキル。このスキルでは、すでに決定済みの変更を文書化します。
• 自分のコードベースでアップグレードを実施してほしい場合 → これは利用者側の作業であり、このスキルの対象外です。このスキルでは、その作業で参照するドキュメントを作成します。
• 日常的なエラーについて、メッセージ文面をキーにしたエラーページを求めている場合 → samber/developer-relations-skills@developer-troubleshooting-docs。アップグレード固有のエラーは、このスキルの対象です。
• 読者が新バージョンの概念を学ぶ必要がある場合 → チュートリアルのスキル。

正確なスキル識別子については、「参考資料」セクションを参照してください。

まず、ガイドが適切な成果物かどうかを判断する

適切でない場合もあります。その判断には、名前の付いた2つの法則が役立ちます。

• チャーンの法則（Software Engineering at Google、第1章。依存関係グラフの拡大に伴い、削除日を告知して利用者に対応を委ねる方法は持続しないため、Google で2012年に採用）：「インフラストラクチャチームは、社内利用者を自ら新バージョンへ移行させるか、後方互換性を保ちながらその場で更新する必要があります。」利用者を管理できる場合（社内サービス、モノレポ、自ら運用するプラットフォーム）は、移行を代行してください。codemod と短い案内を用意し、ガイドは作りません。利用者が実際に他者のコードベースを扱う場合に限り、ガイドを作成してください。
• ハイラムの法則（hyrumslaw.com）：「API の利用者が十分な数に達すると、契約で何を約束したかにかかわらず、システムの観察可能な振る舞いは、誰かが依存しているものになります。」文書化された契約は、影響範囲の全体を示すものではありません。文書化されていない振る舞い、タイミング、エラーテキスト、バグとの互換性も、誰かにとって不可欠です。そのため、変更履歴だけを基にした一覧では、必ず項目が不足します。

作業メモの冒頭に、自分がチャーンの法則のどちら側に該当するかを記してください。自分で移行できた利用者に向けてガイドを書くことは、本来あなたが行うべき作業を利用者に押しつけることになります。

ガイドの種類を選ぶ

このスキルで説明するライブラリ／SDK の形式を標準としてください。スキーマ、クラウド、モバイル、ブラウザー／プラットフォームの移行は、それぞれ大きく異なります。その形式をそのまま適用すると、誤ったドキュメントになります。スキーマ移行は、スニペットを交えた文章ではなく、各手順にロールバック方法を含めた運用手順書です。ライブラリや SDK の単純なアップグレードではない場合は、./references/guide-types-beyond-libraries.md を参照してください。

インタビュー

一度に1つずつ質問し、可能な場合は選択式にしてください。対象のバージョンの組み合わせ、対象範囲、対象ユーザーがわかった時点で終了してください。リスト全体を機械的に進めないでください。

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

1. 何を移行しますか？ ライブラリ／SDK、フレームワーク、CLI、ホスト型 API、データベーススキーマ、モバイルアプリ、または独立してバージョン管理される複数の対象範囲ですか？
2. このガイドが対象とする正確なバージョンの組み合わせは何ですか？ 複数バージョンをまたぐ移行（N-3 → N）にも対応する必要がありますか、それとも1段階の移行のみですか？
3. アップグレードするのは誰ですか？ 自分でタイミングを決めるオープンソースのユーザー、通知期間内に対応する有料顧客、または指示に従う社内チームですか？
4. 破壊的変更の一覧はすでに確定していますか？ それとも、この作業に一覧の洗い出しも含まれますか？
5. どのような自動化がありますか？ codemod、互換性／移行ビルド、lint ルール、バージョン固定ヘッダー、または何もありませんか？
6. バージョン N-1 では、これらの変更についてすでに非推奨警告が出ていましたか？ それとも N でいきなり破壊的変更になりますか？
7. 非推奨 API に関する利用状況のテレメトリはありますか？ 影響を受けるユーザーとその人数はわかりますか？
8. ガイドはどこに掲載しますか？ また、何にリンクする必要がありますか（変更履歴、リリースノート、サポート窓口、ステータスページなど）？
9. リリースとの関係で、ガイドをいつまでに公開する必要がありますか？ リリース当日が期限なら、警告を出す中間リリースは選べず、一段階での移行が必要になります。
10. これは今回限りのメジャーリリースですか？ それとも、今後のすべてのメジャーリリースで再利用する形ですか？ 積み重ねていくなら、互換性ビルド、RFC の承認プロセス、変更ごとの安定したアンカーを推奨します。一度限りなら、この3つはすべて削除します。
11. 移行ツールに使えるエンジニアリングの工数はどれくらいですか？ リリース後の保守担当者は誰ですか？ 担当者が決まっていない場合は、費用を見積もる前に、互換性ビルドと codemod を計画から外してください。

「いいえ」と予想している場合でも、質問7は必ずしてください。テレメトリがあれば、「影響範囲の大きさ順に並べる」判断を推測ではなく測定に基づいて行えます。テレメトリがないこと自体も、ガイドの計画に明記する価値があります。

以下に示す移行経路と自動化の優先順位は、既定の案であり、絶対的なルールではありません。上記の回答と、プロジェクトですでに保有しているものに照らして、両方の順位を見直してください。

• 中間リリースがすでに予定されている場合、段階的な移行経路を追加費用なしで利用できます。
• codemod の既存のコーパスがある場合、codemod を追加費用なしで利用できます。

どちらか一方でも当てはまる場合は、既定の順位にかかわらず、その選択肢を最優先にしてください。

ワークフロー

1. 対象範囲を固定します。 作業メモの冒頭にバージョンの組み合わせと対象一覧を記載し、固定事項として扱います。3つのバージョンの組み合わせまでいつの間にか対象を広げるガイドでは、そのどれについても誰の役にも立ちません。

2. 何が壊れるかを洗い出します。 変更履歴だけでなく、あらゆる情報源を確認します。2つのタグ間の公開 API の差分、変更履歴の Removed／Changed 項目、N-1 が出す非推奨警告、自社のサンプルアプリや内部の利用側での移行コミット、初期導入者からのサポートチケットを調べます。各項目を、削除、名称変更またはシグネチャ変更、動作またはデフォルト値の変更、必要要件の下限、ワイヤー形式／フォーマットの変更に分類します。

3. 影響範囲の大きさを測ります。 テレメトリー、次に依存リポジトリの検索、最後にメンテナーの推定値を使い、変更の影響を受ける読者の数で変更を順位付けします。この順位をガイドの掲載順にします。アルファベット順にも、モジュールごとの順にもしてはいけません。

4. 移行経路の形を選び、ガイドではほかの説明に先立って明示します。3つの形が候補になります。4つ目は必然的に決まります。エンジニアリング時間をかけて移行の道筋を整えることで削減できる、読者の作業時間が多い順です。

   • 段階的移行 - まず N-1 の最後のマイナーバージョンにアップグレードし、影響を受けるすべての呼び出し箇所で非推奨警告を表示させてから、次のバージョンに移行します。参考になる表現は React の v19 ガイドです。まず 18.3 にアップグレードします。18.2 と同じで、v19 で変更される内容に対する警告だけが追加されているためです。警告のみの中間リリースが1つ必要ですが、読者それぞれのビルド出力が、その人専用の洗い出しリストになります。N-1 をまだリリースできる場合は、これをデフォルトにします。

   • 一括移行 - 移行の道筋はなく、あなた側のコストはほぼゼロですが、破壊的変更が一度にすべて読者に降りかかります。変更内容が1回の作業で対応できる範囲に収まる場合、または N-1 がすでに凍結され、段階的移行を選べない場合に採用します。

   • 互換ビルドを使った段階移行 - プロジェクトは移行途中の状態で動作し、その途中の段階で本番環境にリリースします。これは継続的な作業を生みます。移行中は二重の動作経路、機能ごとのフラグ、警告を維持する必要があります。

   • 順次ブリッジ - 他の3つとは順位を競いません。選択するのではなく、バージョン差のポリシーによって強制されるものだからです（Kubernetes は直近3つのマイナーバージョンをサポートし、コンポーネント間のバージョン差に制限を設けています）。このようなポリシーが適用される場合、ガイドは N→N+1 の移行を連ねたものになり、他の3つの形は選択肢から外れます。そのことを最初の画面で明示します。ポリシーが適用されない場合は、選択肢として提示せず、この形をメニューから削除します。

   • 価値：互換ビルドを使った段階移行 > 段階的移行 > 一括移行

   • エンジニアリングと保守の労力：互換ビルドを使った段階移行 > 段階的移行 > 一括移行

   • 効率：段階的移行 > 一括移行 > 互換ビルドを使った段階移行

   この順序では、読者の作業を最も削減できる一方、維持に最もコストのかかる互換ビルドが後回しになります。移行ブランチを動き続ける main に対して保留できない大規模なアプリケーションが利用側に含まれる場合は、これをデフォルトより優先します。そのため、フレームワークは互換ビルドを用意しますが、ライブラリは用意しません。リリース後に誰が保守するかがインタビューで挙がらなかった場合は、選択肢として記載せず削除します。誰も保守しない互換ビルドを導入すると、それを採用したすべてのプロジェクトが移行途中で行き詰まります。

5. 問題があると判明しているバージョンへの経路を明記します。 特定の中間バージョンでリグレッションが発生する場合は、その理由とともに「そのバージョンはスキップし、X に直接進んでください」と記載します。そうしないと、読者は順番に進むというルールに従い、問題があると分かっているバージョンに進んでしまいます。

6. 最低要件から書きます。 ランタイムと言語のバージョン、ピア依存関係、データベースやインフラストラクチャの最低要件、ビルドツールの要件を記載します。最低要件を満たさない読者はコード例までたどり着けません。そのため、最低要件を手順の 9 番目に埋もれさせると、読者の作業時間を無駄にしてしまいます。

7. 破壊的変更ごとに、以下の 6 つの要素からなるブロックを 1 つずつ記載します。 影響範囲の大きい順に並べ、読者が途中で読むのをやめても、影響を受ける可能性が最も高い変更には対応できるようにします。

8. 非推奨化のタイムラインを表にして公開します。 現在非推奨となっているもの、出力される警告レベル、削除されるバージョンを記載します。./references/deprecation-timeline-patterns.md を参照してください。

9. 自動化とその範囲を文書化します。 正確なコマンド、「すべてを実行する」手順、自動化では_対応しない_内容を明示します。自動化をまだ_構築する_必要がある場合は、エンジニアリング 1 時間あたりに節約できる読者の作業時間が多い順に並べます。検索パターンとメッセージの原文 > N-1 の非推奨警告 > lint ルール > codemod > 互換ビルド。**既定では、検索パターンとメッセージの原文を提供します。**これらは各項目の「該当する場合」行としてすでに記載するもので、追加コストがかからず、ユーザーとコーディングエージェントの両方が作業を進める助けになります。それぞれの段階で得られるものと犠牲になるものについては、./references/automated-migration-tooling.md を参照してください。

10. 後片付けのセクションを追加します。 アップグレードの動作確認後に不要になったもの、つまり既定値になった設定オプション、回避策のフラグや依存関係解決のオーバーライド、パッチ、フレームワークにバンドルされるようになったパッケージを読者に伝えます。これらは誰も自発的に削除せず、次回のアップグレードで原因不明の失敗を引き起こすようになります。

11. エラーテキストをキーにしたトラブルシューティングのセクションを追加します。 読者はエラーを検索ボックスに貼り付けて、アップグレードの途中からこのセクションにたどり着きます。そのため、サブシステムの名称ではなく、読者が貼り付ける文字列に一致する内容にします。

12. 以下の合格基準に照らして、クリーンな状態からのアップグレードを検証します。 合格するまで修正と再実行を繰り返します。

13. 計測して記録します。 導入率と問い合わせ抑制率の指標（以下の KPI）を定義します。環境に永続メモリがある場合は、バージョンのペア、経路の形状、非推奨化の期間、サーフェスマトリクスを保存します。次回のメジャーアップグレードでは、この 4 つを再利用できます。

エントリーの構成

各破壊的変更を、同じ 6 つの要素を同じ順序で記載します。この 6 要素の構成と 3 文以内という根拠の上限は、このスキル独自の規約であり、公開済みのテンプレートではありません。この順序は、読者の優先順位に合わせています。自分に影響するか → その理由 → どのような状態になるか → 何を入力するか。

1. 安定したアンカーを持つ、動詞で始まる見出し - Removed:、Changed:、Renamed:、Deprecated:。アンカーは恒久的な識別子です。lint ルール、codemod、サポートへの返信では、ページ全体ではなく個々の変更にリンクするためです。
2. 「該当する場合」の行 - 検出シグナルを記載します。コードベース内で対象を見つける検索パターンと、読者に表示される警告またはエラーの正確なテキストを記載します。変更が自分に該当するか判断できない読者は、すべてを時間をかけて読むことになります。
3. 変更内容とその理由を 3 文以内で記載します。理由があれば対応を促せますが、4 文目を加えると、その効果が失われます。
4. 変更前と変更後のコードを // Before と // After のラベル付きで記載します。貼り付けて使えるだけの内容を含めます。
5. 修正方法：codemod のコマンド、または番号付きの手動手順を記載します。コマンドと曖昧な「手動で更新する」の両方を記載してはいけません。
6. 回避策：互換性フラグ、以前の動作に戻す設定、または「回避策はありません」と明記します。回避策がないという情報も重要です。何も書かないのは情報になりません。

記入用テンプレートと、良い例に加えて 2 つの悪い例については、./references/breaking-change-entry-template.md を参照してください。

誰が書くのか、そしてそれを必須にするゲート

破壊的変更を行ったエンジニアが技術的な内容を担当し、ライターやアドボケイトが明確さ、構成、公開を担当します。この分担のなかでガイドが抜け落ちます。それぞれの担当者が、もう一方が下書きを作ると思い込むためです。ドキュメントをコードとして管理するプロジェクトでは、移行に関する注記を変更と同じプルリクエストで公開するため、APIを変更した人が必然的に最初の執筆者になります。

より強力な解決策は、コードをマージする前にドキュメントを必須とするガバナンスゲートです。次の3つのプロジェクトでは、この仕組みを運用しています。

• EmberのRFCテンプレートでは「How we teach this」セクションが必須であり、Recommended段階ではRFCの完了前に、その機能をガイドに組み込む必要があります。
• Rust RFC 1636はEmberのゲートを取り入れました。How We Teach Thisの要件が満たされるまで、安定化を進めてはなりません。
• Kubernetes KEPでは、Upgrade / Downgrade StrategyおよびVersion Skew Strategyのセクションが必須です。KEPが未完成の場合、エンハンスメントの凍結時にリリース対象から外されます。

プロジェクトにRFC、KEP、または設計ドキュメントのプロセスがある場合は、ガイドではなく、そのプロセスにセクションを追加することを提案してください。これにより、今後の破壊的変更がすべて自動的にガイドにつながります。ただし、書面上のゲートにも適用の仕組みが必要です。Rustの内部向けスレッドでは、RFC 1636の変更履歴に関する部分が実際には一度も実施されなかったと認めています。

対象読者の違い

各読者向けの項目自体は同一です。検出のシグナル、変更前後の状態、回避策は同じです。異なるのは次の3点です。

• オープンソース／セルフサービスの読者は自分で選んでアップグレードするため、ガイドは何もしない選択肢と競合します。
  • アップグレードで得られるものを、冒頭の2行で説明します。
  • 移行期間は日付ではなくリリース数で示し、どのバージョンがいつまでセキュリティ修正を受け取れるのかを明確に伝えます。
  • 失敗例：読者がすでにアップグレードを決めていることを前提としたガイド。
• 商用／契約上の読者は、日付が迫るためにアップグレードします。
  • 期限と告知期間を最初に示します。
  • サポート窓口とエスカレーション経路を、告知メールだけでなくガイド内にも記載します。
  • ロールバックの手順を示し、ベンダー側で誰が切り替えを実施するのか、またその前に顧客が何をする必要があるのかを伝えます。
  • マネージド環境やエンタープライズ環境には、それぞれ独自の期限を設けた回避策を用意し、公開前にサポート部門と法務／コミュニケーション部門の承認を得るよう原稿を回します。
  • 失敗例：日付も担当者名もなく、技術的には完璧でも、エンタープライズの読者がスケジュールを立てられないガイド。
• 社内／義務付けられた読者には、動機付けよりも担当範囲のマップが必要です。
  • 影響を受ける各サービスの担当チーム、追跡用のイシュー、旧バージョンをデプロイできなくなる凍結日を記載します。
  • このガイドを書く前に、Churn Ruleをもう一度確認します。

独立してバージョン管理されるインターフェース

ライブラリのアップグレードはローカルで、利用は任意です。一方、ホスト型APIのアップグレードは、他者の稼働中の本番システムの動作を変えるため、ガイドにはライブラリのガイドでは不要な調整事項を追加する必要があります。

• デフォルトを切り替える前に、リクエストごとに新バージョンをテストするためのピン留めの仕組み。
• サーバーSDK、ブラウザーバンドル、モバイルSDK、Webhookペイロードにまたがる互換性マトリックス。
• 識別子や列挙型の変更によるデータレイヤーへの影響。
• 切り替えとロールバックの手順。

APIの契約差分パイプラインで、各破壊的変更の出典と対応がすでに一覧化されている場合は、その項目からガイドの変更一覧を作成します（samber/developer-platform-skills@api-changelog-automation）。

連携して更新する必要のあるパッケージ群をリリースする場合は、バージョン整合性チェックを追加します。パッケージ群の各パッケージを同一バージョンにし、関連ライブラリはドキュメントに記載された互換バージョンにそろえます。パッケージ群を一部だけアップグレードすると、破壊的変更が原因のように見えるエラーが発生しますが、実際にはそうではありません。

移行のいずれかの部分が、自分たちの管理するネットワーク境界を越える場合は、./references/api-version-migration.mdを参照してください。

機械可読な要件

人間だけでなく、コーディングエージェントもこのガイドを実行すると想定してください。この想定によるコストはなく、人間にとっても改善になります。このセクションではこのページのみを対象とします。ドキュメント一式をエージェントが利用できるようにするのは、samber/developer-relations-skills@coding-agent-docs-optimization の役割です。

• エラーや警告の文字列は、句読点も含めて正確に引用してください。エージェントも検索ボックスも、文字列そのものを照合します。
• インポートを含む、完全で実行可能なスニペットを提示してください。読者が正しい位置に配置しなければならない断片は使わないでください。
• バージョンの組み合わせごとに正規 URL を 1 つにし、変更ごとに安定したアンカーを付けてください。リリースごとに場所が変わるガイドでは、サポートがこれまでに共有したリンクがすべて壊れてしまいます。
• バージョンの最低要件は、文章（「最近の Node バージョン」）ではなく、機械で確認できる比較（Node >= 20.19）で示してください。
• 移行手順はガイド内に記載してください。「背景についてはリリースブログ記事を参照してください」は問題ありませんが、「手順についてはブログ記事を参照してください」では、プログラムから読んでいる人が行き詰まります。
• 変動するパッチバージョンを文章に埋め込まないでください。ガイドが対象とするバージョンの組み合わせを固定し、最新リリースは変更履歴に記載してください。

呼び出し例

ゼロからの下書き。「来月、Node クライアントの v3 をリリースします。破壊的変更が 14 件あり、codemod はまだありません。移行ガイドを作成してください。」→ インタビューを実行し（質問 1～5 で止めます）、次に、変更の種類で分類した一覧表、根拠の出典を添えた影響範囲の順位付け、推奨する手順の構成、ライブラリのアウトラインに沿ったガイドの完全な下書きを作成します。codemod がないことは、取り繕うべき不足ではなく、判断事項として明記してください。

既存ガイドの監査。「こちらが v2→v3 のアップグレードページです。サポートへの問い合わせが増え続けています。」→ 6 つの合格基準に照らしてページを評価し、検出シグナルまたは変更前／変更後のブロックが欠けている項目をすべて列挙し、順序に問題があればその不備を指摘したうえで、優先順位付きの修正リストと、上位 3 項目の書き直した文章を提示します。

非推奨化の途中。「2.4 で 4 つの API を非推奨にしました。3.0 で削除する予定ですが、今何を公開すればよいでしょうか。」→ 非推奨化のタイムライン表に加えて、移行ガイドではなく削除を主題とするページ（「3.0 で何がなくなるか」）を作成し、暫定リリースで各項目に必要な警告レベルを明記します。

いずれの場合も、期待される出力形式：

1. Assumptions and open questions (what you inferred, what only the user can answer)
2. Inventory table: change | type | blast radius | evidence
3. Recommended path shape, with the reason in one line
4. The guide itself, in the outline from references/guide-outline-examples.md
5. Verification plan: the cold-run project, who runs it, what gets measured
6. KPI list with where each number comes from

破壊的変更の対象が多い場合、または意見が分かれている場合は、セクション 4 の執筆に入る前に、セクション 1～3 を検証用に提出してください。順序を誤って 14 項目を書き直すより、1 往復増やすほうが低コストです。

合格基準

コールドアップグレードを実行して検証します。バージョン N の実際のプロジェクト（サンプルアプリ、社内の利用プロジェクト、またはコミュニティプロジェクト）を用意し、ガイドの内容だけを使ってアップグレードします。キーボードを操作するのは、ガイドを執筆していない人です。以下の6項目をすべて満たしたら公開できます。この6項目は、このスキル独自の基準であり、業界標準ではありません。それぞれの失敗は執筆者には気づかれにくく、読者には大きな負担となるため、絶対に満たす必要があります。

1. 網羅性。 タグ間の差分にある、削除された、または動作が変更された公開シンボルすべてに項目があること。ガイドを API の差分と照合してください。変更履歴を項目の一覧として信用してはいけません。ヒュラムの法則により、その差分でさえ見落としがあるため、サポートがすでに把握している破損も追加してください。
2. 検出可能性。 各項目に検索パターンと、エラーまたは警告の正確な文言が記載されていること。
3. 十分性。 ガイドに記載されていない編集を一切行わずにアップグレードが完了すること。文書化されていない編集は、読者の失敗ではなく欠陥です。
4. 自動化に関する誠実さ。 コードモッドを掲載する場合は、すべてテストプロジェクトで実行済みであり、コードモッド適用後に残る作業がガイドに記載されていること。その後、型チェックとテストスイートが成功すること。
5. 経路の妥当性。 複数バージョンをまたぐアップグレードを案内する場合は、案内する中で最も古いバージョンから、経路全体を実行していること。
6. 自己完結性。 読者が次に何をすべきか知るために、ソース、変更履歴、イシュートラッカーを開く必要がないこと。

エコシステムが実行可能なドキュメントに対応している場合は、ガイド内のコマンドを CI に組み込んでください（Rust の cargo test --doc と mdbook test が参照実装です）。そうすれば、コンパイルできなくなったコード例は静かに劣化するのではなく、ビルドを失敗させます。コールド実行にかかった時間を計測し、想定作業時間として公開してください。計測していない所要時間を記載してはいけません。./references/validation-and-adoption-metrics.md を参照してください。

網羅性を大規模な対象で確保するのが難しい場合は、項目を削除するのではなく、ガイドをモジュールごとに分割し、検証も同様に分割してください。Google の Rosie プラットフォームは、所有権の境界に沿って大きな変更を分割し、それぞれを個別にテスト、レビュー、提出するという業界での先例です（Software Engineering at Google、第22章）。不完全なガイドは、ガイドが信頼できないことを読者に気づかれないまま教えてしまいます。

KPI

この順序で計測します。報告される順ではなく、配線にかかる時間あたりの価値に基づいています。

• アップグレード千件あたりのチケット数：アップグレードエラーに言及しているチケット数と、その大半を発生させている変更です。無料で確認できます。サポートではすでに収集されています。該当する変更のエントリを書き直してください。
• 非推奨警告のテレメトリー：削除リリース前にゼロに近づいているかを追跡します。段階的な移行経路の仕組みはすでに必要なため、集計には1時間かかります。リリースの1か月前になっても横ばいなら、削除日の設定が間違っているか、ガイドが読者に届いていません。
• コードモッドの実行率：ツールで報告される場合は手動移行と比較します。報告される環境では無料で確認できますが、報告されない環境では利用できません。
• ガイドの利用状況：ページ内でのエラー文字列の検索と、サポートチャネルへの移動です。どちらも、必要なエントリがない、または見つけられないことを示すシグナルです。ドキュメント分析には1時間かかります。
• 導入曲線：30／60／90日時点でN+1を使っているアクティブなインストールまたはアカウントの割合を、前回のメジャーリリースの曲線と比較します。移行が成功したかを示す唯一の指標であり、90日間にわたるインストールまたはアカウントのテレメトリーの結合が必要なので、継続的に取り組む作業です。プラットフォームによる強力な強制措置がある移行であっても、長いテールは普通です。最後の約15%は、ドキュメントの問題としてではなく、個別に対応するアカウントとして計画してください。このスキルの15%のしきい値の基準となった公開済みの曲線については、./references/validation-and-adoption-metrics.mdを参照してください。
• 移行しきれていない利用者：期限後もNを使い続けている、名前が特定されたアカウントまたは主要な依存先です。これはサポートチームとカスタマーサクセスチームが対応するリストであり、割合ではありません。

導入曲線と移行しきれていない利用者のリストは、同じ程度の工数がかかるため、セットで用意します。同じIDの結合から両方が得られ、曲線は集計値、リストはそのテールにあたるため、その結合ができるまではどちらも作成できません。コードモッドの実行率とガイドの利用状況も、別の理由で工数が同程度です。いずれも、他者がすでに運用しているシステムを1時間かけて調べるもので、移行全体ではなく、特定の成果物に関する問いに答えます。

この順序では、ページ上で最も価値の高い数値である導入曲線の優先度が下がります。削除日について顧客や経営陣への説明が必要な場合は、導入曲線を最優先にし、リリース前にIDの結合に着手してください。リリース後に始めると、最初の90日間はすでに測定できません。ホスト型APIの場合、samber/developer-platform-skills@integration-health-monitoringを使うと、移行しきれていない利用者のリストを、担当者付きの統合ごとの調査リストに変換し、期限までの案内を実施できます。

（段階的な停止、強制削除、エンタープライズ向けの回避策の廃止などの）厳格な強制措置は、導入曲線が明らかに横ばいになってから始めてください。この種の移行は、公開されている事例でも一貫して、そこに達するまで数か月ではなく数年かかっています。曲線については上記の参考資料を参照してください。

失敗パターン

症状	対処
ガイドがタイトルを変えただけの変更履歴になっている	各項目を読者が行うアクションとして書き直し、読者にとって何も変わらない内容は削除します
変更がモジュール別またはアルファベット順に並んでいる	影響範囲の大きさ順に並べ替え、誰もが直面する変更を先頭にします
コードを示さず「使い方を適宜更新してください」としている	変更前／変更後のブロックを追加します。例を書けない場合は、公開するには変更内容の理解が不十分です
変更が適用されるかどうか読者が判断できない	検索パターンと警告文の原文を記載した「影響を受ける場合」の行を追加します
実行時に一度も警告せずに非推奨機能を削除している	削除前の中間リリースで警告レベルを引き上げます。手遅れの場合はその旨を伝え、旧バージョンのサポート期間を延長します
複数バージョンを飛ばすアップグレードがサポートされていないのに、その説明がない	サポート対象のアップグレード経路を明記します。古いバージョン向けに順序立てた手順を示すか、段階的なアップグレードに誘導します
リリースごとにガイドをその場で書き換えている	バージョンの組み合わせごとに正規のページを1つ用意し、安定したアンカーを付けて公開し続けます
エンタープライズの読者が計画に使える日付を把握できない	期限、告知期間、ロールバックの説明を公開します
ガイドの各手順でベンダーのツール名を挙げている	機能について説明し、ツール名は単独で更新できる1つの連携に関する注記にまとめます
実測した実行なしに所要時間の見積もりを公開している	コールドアップグレードを実行してその数値を公開するか、何も公開しないようにします
スキーマの変更をスニペット付きの文章で説明している	各手順のロールバック手順を含むランブックに書き直します。ガイドの種類に関するリファレンスを参照してください
サポート対象外の経路を中途半端にサポートしている	読者を明示的に別の案内へ誘導します（「2.xを使い続けてください。その理由はこちらです」）。メインの手順に残したままにしないでください

参考資料

• 変更ごとのブロックテンプレートと、良い例・悪い例のペアについては、./references/breaking-change-entry-template.mdを参照してください。
• ページ全体の構成（ライブラリ／SDK、ホスト型 API）と、望ましくないアウトラインについては、./references/guide-outline-examples.mdを参照してください。
• 警告レベルの段階、リリース回数に基づく期間、タイムライン表の形式については、./references/deprecation-timeline-patterns.mdを参照してください。
• codemod エコシステム、互換性ビルド、カバレッジの境界を示す文言については、./references/automated-migration-tooling.mdを参照してください。
• ホスト型 API に関する詳細（バージョン固定、サーフェスのマトリクス、Webhook、切り替え、ロールバック）については、./references/api-version-migration.mdを参照してください。
• スキーマの運用手順書、クラウド／プラットフォーム、モバイル、ブラウザー API の移行については、./references/guide-types-beyond-libraries.mdを参照してください。
• 実行可能なドキュメントの CI、初見でのウォークスルー、codemod コーパスのテスト、導入ベンチマークについては、./references/validation-and-adoption-metrics.mdを参照してください。
• 上記の主張を裏付ける公開ポリシー、数値、名称のある手法については、./references/sources.mdを参照してください。
• samber/developer-relations-skills@developer-tutorial（読者がコードを移植するだけでなく、新バージョンの概念を学ぶ必要がある場合）
• samber/developer-relations-skills@tech-press-relations（破壊的変更を伴うメジャーバージョンの報道対応）
• samber/developer-relations-skills@oss-release-policy（このガイドが適用する非推奨化期間、サポート終了日、破壊的変更の定義）
• samber/developer-relations-skills@developer-docs-structure-audit（ドキュメントサイト内でガイドを配置する場所）
• samber/developer-relations-skills@docs-versioning-strategy（ガイド公開後に旧バージョンのドキュメントを公開状態のままにするか、凍結するか、アーカイブするか）
• samber/developer-platform-skills@api-versioning-policy（バージョン方式、非推奨化期間、提供終了までのタイムラインの選定）