Version an endpoint and keep the old one working
A breaking change released behind a new version, with the old one kept working until every user has moved.
The ticket
Version one route and provide a compatibility shim for the previous shape.
Acceptance criteria
- Both versions are covered by tests
- The old version keeps working unchanged
- A deprecation date is recorded and communicated
- Usage of the old version is measurable so the removal can be evidence-based
What lands as proof
Both versions under test plus usage measurement, which is what makes the eventual removal safe.
Why teams defer it
- Versioning is a commitment to maintain two shapes, which nobody wants to sign up for.
- Without usage data nobody can say when the old one is safe to remove, so it lives forever.
Questions
- What does the agent actually change?
- The ticket is scoped to one outcome: version one route and provide a compatibility shim for the previous shape. Work that serves that outcome is in scope, and anything outside it is left for a separate ticket, so the pull request stays reviewable.
- How do I know the work is done?
- The pull request carries the evidence, not only the diff. Here that means old and new both covered, the deprecation date recorded, so a reviewer can confirm the result without reproducing the work locally.
- How much oversight does this need?
- The run stops for the plan, and the review bar is raised afterwards so that smaller suggestions block the merge too, not only serious findings.