A backward compatibility policy defines which API changes preserve existing users’ reasonable expectations. Because almost any change can break some code, classify changes according to what users could reasonably expect a particular API version to support. section 24.2.2
Choose the policy deliberately rather than deciding case by case:
- Favor stability when users depend on predictable behavior, even if that limits new features, fixes, and behavioral improvements. section 24.4.2
- Favor rapid change when users prioritize new functionality, bug fixes, security patches, and infrastructure upgrades. section 24.4.2
- Recognize that perfect stability is difficult: operating-system, supplier, library, and security changes can still alter observable behavior. section 24.4.2
- Set an explicit position between these extremes; leaving the policy implicit tends to frustrate users. section 24.4.2
A semantic change can break valid-looking code
Suppose an addition API changes floating-point arithmetic to fixed-point arithmetic to correct precision problems. The change may appear compatible because the method signature remains unchanged, yet callers depending on previous results may observe different behavior. Similarly, changing message delivery timing can make two consecutive sendMessage calls fail at the sending step or cause a later listMessages length check to fail. section 24.2.2 section 24.2.2
Evaluate compatibility from the user’s perspective, document the chosen stability–functionality balance, and treat semantic behavior as part of the contract—not only method signatures. section 24.2.2 section 24.4.2
