Background
layout 変更や scaffold/init の前提を変える変更では、コード差分そのものだけでなく、利用者がどう移行するか、実行前に何を準備すべきか、どこで待つべきかを同時に伝える必要があります。
migration guidance があっても、environment readiness や実行時の注意書きが抜けると、利用者の試行錯誤や補足対応が発生しやすくなります。
Problem
breaking change を含む PR で、migration guidance、environment readiness、starter/scaffold expectation などが毎回安定して揃う運用になっていない可能性があります。
その結果、以下の問題が起こりえます。
- 利用者が移行手順を誤解する
- 実行前提の不足により再現でつまずく
- merge 後に補足 docs や cleanup が必要になる
- reviewer が "何が揃えば受け入れ可能か" を判断しづらい
Proposal
breaking layout change を含む PR では、最低限の readiness / migration checklist を必須化したいです。
対象項目は少なくとも以下を想定します。
- Upgrade note
- Migration impact
- Environment readiness
- Starter / scaffold expectation
ここでの目的は文量を増やすことではなく、利用者が移行と再現に必要な前提を落とさず読める状態を標準化することです。
Expected benefit
- breaking change の説明漏れを減らせる
- 利用者の移行時の迷いを減らせる
- reviewer が受け入れ条件を確認しやすくなる
- merge 後の補足 docs や cleanup の必要性を下げられる
Definition of done
- breaking layout change を含む PR で確認すべき checklist 項目が定義される
- 当該変更では readiness / migration 情報を明示する運用が決まる
- release note または guide への反映方針が整理される
- 同種の breaking change で説明不足が再発しにくい状態になる
Background
layout 変更や scaffold/init の前提を変える変更では、コード差分そのものだけでなく、利用者がどう移行するか、実行前に何を準備すべきか、どこで待つべきかを同時に伝える必要があります。
migration guidance があっても、environment readiness や実行時の注意書きが抜けると、利用者の試行錯誤や補足対応が発生しやすくなります。
Problem
breaking change を含む PR で、migration guidance、environment readiness、starter/scaffold expectation などが毎回安定して揃う運用になっていない可能性があります。
その結果、以下の問題が起こりえます。
Proposal
breaking layout change を含む PR では、最低限の readiness / migration checklist を必須化したいです。
対象項目は少なくとも以下を想定します。
ここでの目的は文量を増やすことではなく、利用者が移行と再現に必要な前提を落とさず読める状態を標準化することです。
Expected benefit
Definition of done