Skip to content

docs/process: require readiness and migration checklist for breaking layout changes #711

@mk3008

Description

@mk3008

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 で説明不足が再発しにくい状態になる

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions