Backward compatibility lets a changed module or interface continue to understand clients using an earlier contract. It matters most when modules evolve independently: a team can deploy a feature without waiting for every client team to update, and clients avoid breaking when internal details change. section 7.2.2 section 7.5
Treat a public interface as a promise. Keep it simple, stable, and focused on shielding clients from module complexity. Clients should not need to revise their interaction whenever implementation details change; clear extension mechanisms can accommodate variation without making a module serve one client through bespoke changes. section 7.2 section 7.2.1
Evolving a request contract
Suppose version 2 adds information to a module request or changes its allowed enumerated strings. A backward-compatible API accepts requests formed under version 1 as well as version 2, handling information that is absent from the older request or differs under the newer contract. This adds API-handling complexity, but prevents older clients from failing immediately. section 7.2.2
Use backward compatibility selectively rather than as an automatic rule:
- Prefer it when independently owned or separately deployed modules cannot all be changed together. section 7.2.2
- Consider a coordinated breaking change when an abstraction has few clients and all dependent code can reasonably be updated. section 5.1.4
- When compatibility cannot be kept, notify clients well in advance and give them time to change. section 7.2.2
- Document unavoidable coupling and automate pipeline alerts for breaking changes. section 7.1.4
Compatibility is not free. Supporting multiple request forms raises module complexity, while continually changing an interface spreads maintenance work to every client. Refine abstractions from real usage, but balance improvement against the cost of breaking dependents. section 5.1.4 section 7.2.2
