Backward compatibility keeps existing clients and dependent systems working as a public contract evolves. Treat it as a trust-preserving practice: communicate changes, document alternatives, and preserve compatibility for as long as users need to adapt. section 9.4.2 section 9.5
Manage an evolving interface with two complementary actions:
- Communicate the change through documentation, changelogs, deprecation policies, and direct or indirect user notices. section 9.4.2
- Preserve the old interface while users migrate, then use semantic versioning to signal additions, fixes, and breaking changes. section 9.4.2 section 9.5
Make removal predictable
A Java library can mark an old method as @Deprecated(since = "2.1", forRemoval = true), document its replacement, and warn users before removing it. section 9.4.2
@Deprecated(since = "2.1", forRemoval = true)
public void generateReport() { ... }
A compact Java annotation communicates when an API became deprecated and whether its removal is planned. section 9.4.2
