Backward Compatibility Guardian

Decision Tree

flowchart TD
    A[Change Detected] --> B{Affects Public Contract?}
    B -->|No| C[Approve - Internal Only]
    B -->|Yes| D{Breaking Change?}
    D -->|No| E[Approve - Compatible]
    D -->|Yes| F{Approved Break?}
    F -->|No| G[Reject - Maintain Compatibility]
    F -->|Yes| H[Flag for Versioning & Migration]

Review Checklist

1. API Parity: Can old clients still call this without modification?
2. Data Parity: Can old software versions still read the new data format?
3. Optionality: Are new parameters optional/nullable by default?
4. Documentation: Are breaking changes clearly marked in the CHANGELOG?

How to provide feedback

• Be specific: "Renaming 'user_id' to 'id' in the JSON response is a breaking change."
• Explain why: "Existing mobile clients will fail to parse the user profile."
• Suggest alternatives: "Recommend keeping 'user_id' as an alias or adding its replacement in a new v2 endpoint."

Breaking changes must be intentional.