Define/Use annotation(s) to define the code that is part of the public API

[Claudenw]

Current state

Currently we have no distinction between methods signatures and components that are part of the public API (for example configuration properties) and those that are subject to change within a major semantic version.

Issue

Breaking changes, and changes to public APIs, require a bump in the major version number. However, there have been changes that did not change methods that are designed to be public facing. This resulted in deprecation notes and convoluted code to handle the deprecation.

Proposed solution

There are a number of ways to address this problem. I would like to see us adopt a process that is automated so that we can use annotations to annotate code that is or is not part of the external API and therefore may not be changed except at a major release as per the semantic versioning spec.

Either we annotate packages/classes as locked except for major release or we annotate them as subject to change within a major release. Then we can use one of the code checking libraries to ensure that there is not a binary incompatibility within major versions.

Alternatively we could declare that anything that is "locked" is within a specific package and everything else is subject to change. I think this approach would impose a structure on the classes that is orthogonal to the expected structure of grouping where used.