第09章：互換ポリシーを文章にする📜🖊️
この章のゴール🎯
- 「互換性をどう守るか」を文章で説明できるようになる✨
- チームや利用者が迷わないように、1枚（A4）で読めるルールに落とせるようになる🧡
- 「非推奨 → 移行 → 削除」の流れを、ちゃんと運用できる形にする🚧➡️✅
互換ポリシーってなに？🤝
互換ポリシーは、ざっくり言うと 「このAPI（またはライブラリ）を安心して使うための約束ごと」 だよ✨ コードや型だけじゃなくて、運用の約束（いつまで古い版を助ける？どう告知する？）まで含めて書くのがポイント📣
9-1. まず決める：このポリシーの“読者”は誰？👀
ポリシーって、読者によって必要な情報が変わるよ〜！
- 利用者（呼び出し側）：壊れる？いつ移行？どこ見ればいい？😵💫
- 提供者（あなた/チーム）：何を守る？どう出す？いつ消す？🧰
- 未来の自分：半年後に「え、これ破壊？破壊じゃない？」って揉めないため🤣
9-2. “A4 1枚”に入れるべき必須パーツ🧩✨
ここからが本題！この8つが入ってると強いよ💪
① 公開API（Public Surface）の定義🎭🚪
「どこまでが“約束”か」を先に固定するのが超大事！
- 例：
exportしてる関数/型、HTTP APIのエンドポイント、イベント名とpayload…など
書き方のコツ
- 「公開API＝ここ」
- 「それ以外は内部で、互換保証しない」 この線引きがあると、安心して内部を改造できる🔧✨
② バージョニング規則（基本はSemVer）🔢✨
互換ポリシーの中核はこれ！ 破壊的変更が入ったらMAJORを上げる、っていう基本ルールがあるよ。(Semantic Versioning)
-
MAJOR.MINOR.PATCH- MAJOR：後方互換が壊れる変更（利用者の修正が必要）💥
- MINOR：互換を保った機能追加✨
- PATCH：互換を保ったバグ修正🐛
③ 「破壊的変更」の判定ルール📏
第8章で作った「破壊変更リスト」を、ここに短く載せよう📝 例（よくあるやつ）👇
- 関数の削除、引数の必須化、戻り値の型変更
- JSONの必須フィールド追加（＝古いクライアントが死ぬかも）
- 例外/エラーの意味が変わる（同じコードでも意味が別）😱
④ 非推奨（Deprecation）ルール🚧📣
「いきなり削除しない」ための礼儀作法だよ🧁✨
-
非推奨にしたら：まず告知📣
-
可能なら：代替手段（新API）を用意🎁
-
期限を決める：**いつ削除される？**🗓️
-
実装で目立たせる：JSDocの
@deprecatedが便利✨- TypeScriptは
@deprecatedを型システムに取り込んでるよ(TypeScript) - Visual Studio Code も
@deprecatedの打ち消し表示（取り消し線）をサポートしてるよ(Visual Studio Code)
- TypeScriptは
⑤ サポート範囲（どの版まで面倒みる？）🛟
ここが曖昧だと炎上しがち…！🔥 よくある決め方👇
- 最新のMAJORの最新MINORのみサポート（シンプル）
- 最新 + 1つ前のMAJORも一定期間サポート（優しめ）
- セキュリティだけは例外で古い版にもPATCH提供（やるなら明記）🔒
⑥ 変更の伝え方（CHANGELOG / リリースノート）📰
「どこを見れば変更が分かる？」を固定しよう✨ 定番は Keep a Changelog 形式！カテゴリが分かりやすいよ🧡(Keep a Changelog)
- Added / Changed / Deprecated / Removed / Fixed / Security …みたいに分ける📚(Keep a Changelog)
⑦ 移行ガイドの方針🪜
破壊があるなら、利用者が困らないように👇
- “何が変わった？”
- “何をどう直す？”（例付き）
- “段階移行できる？”（旧新併存できる？）
⑧ 例外ルール（緊急時）🚑
- 重大バグ・セキュリティは、ルールを少し曲げることもある その代わり 「どう曲げるか」も文章にする と安心だよ🔒✨
9-3. すぐ使える！互換ポリシー（A4 1枚）テンプレ📄✨
そのままコピペして、[] を埋めるだけでOKだよ🧡
## 互換ポリシー（Compatibility Policy）
## 1. このドキュメントの目的
- 本ポリシーは、[プロダクト/ライブラリ名] の利用者に対して互換性と変更の扱いを明確にする。
## 2. 公開API（互換保証の対象）
- 公開APIは以下を指す：
- [例：exportしている関数/型]
- [例：HTTP APIのエンドポイントと入出力]
- [例：イベント名とpayload]
- 上記以外（内部実装）は互換保証の対象外。
## 3. バージョニング
- バージョンは MAJOR.MINOR.PATCH に従う。
- MAJOR：後方互換を壊す変更（利用者の修正が必要）
- MINOR：後方互換を保った機能追加
- PATCH：後方互換を保ったバグ修正
## 4. 破壊的変更（Breaking Changes）の定義
- 破壊的変更とは、公開APIを利用する既存利用者が修正なしに動かなくなる変更。
- 例：
- [例：関数削除]
- [例：必須パラメータ追加]
- [例：戻り値の型変更]
- [例：JSON必須項目追加]
## 5. 非推奨（Deprecation）
- 非推奨は、削除の前段階として告知する。
- 非推奨にする場合：
- 代替手段（新API）を提示する
- CHANGELOGに記載する
- コード上で @deprecated を付与する（可能なら）
- 非推奨期間：原則 [例：次のMAJORが出るまで / 90日] のいずれか長い方
- 削除は原則 MAJOR アップデートで行う。
## 6. サポート範囲
- サポート対象は [例：最新MAJORの最新MINORのみ / 最新と前MAJORの2系統]。
- セキュリティ修正の扱い：[例：必要に応じて古い版にもPATCH提供 / 最新のみ]
## 7. 変更の通知
- 変更は CHANGELOG に記載する（カテゴリ：Added/Changed/Deprecated/Removed/Fixed/Security）。
- 破壊的変更がある場合は、移行ガイドを必ず用意する。
## 8. 例外（緊急対応）
- 重大な不具合・セキュリティについては例外対応を行う場合がある。
- その際も、影響範囲と回避策を告知する。
9-4. TypeScriptでの「非推奨」の見せ方（小ネタだけど超効く）✨
たとえば「古い関数を残しつつ、新しい関数へ誘導」したい時👇
/**
* @deprecated Use `parseUserIdV2` instead.
*/
export function parseUserId(input: string): number {
return Number.parseInt(input, 10);
}
export function parseUserIdV2(input: string): number {
// 新しいルールに合わせた実装…みたいなイメージ
const n = Number(input);
if (!Number.isFinite(n)) throw new Error("invalid user id");
return n;
}
@deprecatedは TypeScript側で扱われるし(TypeScript)、VS Codeでも見た目で分かりやすくなるよ(Visual Studio Code)- これだけで「削除じゃないけど、使わないでね」が伝わるの強い💪💕
9-5. ミニ演習📝🧡（A4 1枚を完成させよう）
演習1：テンプレ穴埋め（15分）⏱️
上のテンプレをコピペして、まずこれだけ埋めよう👇
- 公開API（箇条書き3〜7個）
- 非推奨期間（数字で！例：90日）
- サポート範囲（最新のみ？前MAJORも？）
演習2：3つの変更を分類（10分）🎮
次の3つを MAJOR / MINOR / PATCH に分類して理由も書く✍️
- ① 関数の引数を「任意→必須」にした
- ② JSONに「任意フィールド」を追加した
- ③ 型注釈ミスを直した（挙動は同じ）
9-6. よくある事故パターン😱💥（ポリシーで防げる！）
- 「意味を変えただけ」事故：型は同じでも意味が変わると実質破壊💥
- ドキュメント未更新：利用者が古い仕様で実装して詰む🧊
- 非推奨の期限がない：「いつ消えるの？」って不安だけ残る🥺
- CHANGELOGがない/薄い：移行のヒントがゼロで地獄👻 → Keep a Changelog のカテゴリ分けが助けになるよ(Keep a Changelog)
9-7. AI活用🤖✨（そのままコピペOK）
① ポリシーを“短く分かりやすく”整える🧁
この互換ポリシーを、読みやすい日本語でA4 1枚に収まる分量に整えて。
専門用語は必要最小限にして、箇条書きを増やして。
② 「矛盾してない？」レビューしてもらう🔍
この互換ポリシーの文章に、矛盾・抜け・曖昧な表現がないかチェックして。
特に「サポート範囲」「非推奨期間」「破壊的変更の定義」が曖昧なら指摘して。
③ 変更を出した時のCHANGELOG文を作る📰
次の変更内容から、Keep a Changelog形式でCHANGELOGの追記案を書いて。
カテゴリ（Added/Changed/Deprecated/Removed/Fixed/Security）も正しく選んで。
変更内容：<ここに箇条書きで貼る>
④ “非推奨のお知らせ”テンプレを作る📣
次のAPIを非推奨にする告知文を作って。利用者が困らないように
(1) 代替API (2) 移行手順 (3) 削除予定日 を必ず入れて。口調はやさしく。
非推奨API：<名前>
代替API：<名前>
削除予定：<日付 or バージョン>
まとめ（この章でできるようになったこと）🎀
- 互換性を「守る気持ち」じゃなくて、守れる文章にできた📜✨
- 非推奨→移行→削除の流れを、利用者が安心できる形にできた🚧➡️✅
- CHANGELOGや
@deprecatedみたいな仕組みで、運用で守る道具もそろった🧰💖