In the Java client libraries our goal is to not introduce breaking API changes. However, there are times when APIs need to evolve to take into account changes in requirements, understanding, or user demands. There are various ways in which an API may evolve:

• Adding or removing an additional argument into a method.
• Changing the type of an argument into a method.
• Changing the return type of a method.
• Adding additional methods or abstract methods to an interface / abstract class.

In all of these cases, if all we did was the change as outlined above, we would be introducing breaking API changes that will break users of our existing release when they upgrade to our next release.

Our position is to never release a client library that is breaking for users, except in certain, pre-agreed releases where our semantic versioning increments its major value (however, not all major-increments are necessarily breaking).

For a very long time, Java releases applied the appropriate deprecation annotations, but the API lingered through many releases to ensure backwards compatibility. More recently, the final act of following through on deprecation by removing deprecated functionality has become increasingly accepted. The JDK in more recent releases has taken to cleaning out some deprecated functionality, and improving the @Deprecated annotation to enable identification of when an API was deprecated, and if it is planned for removal.

It could be said that deprecation is baked into the Java ethos. We should strive to see deprecation and removal as a last resort, but also as a useful tool in our toolset to ensure that we deliver developers the best developer experience.

Whenever we decide to deprecate an API, we should use the JavaDoc @deprecated tag to document the deprecation, as well as the @Deprecated annotation.

Before an API is deprecated, it needs to be specifically approved by other Java engineers in the team, as well as the Java architect.