Use Semantic Versioning
Semantic versioning is a convention in which “version numbers and the way they
change convey meaning about the underlying code and what has been modified from one
version to the next.” It has a detailed specification
that lays out a number of rules designed to align with common practice.
- For the purpose of semantic versioning, the stable surface of a library
serves as its public API.
- Annotations can mark features (classes, methods, etc.) as unstable,
and thus not part of the public API, such that semantic versioning rules do not apply.
- Examples of annotations:
- Guava uses
- grpc-java uses
- Google-cloud-java uses
- Library documentation should point users to a tool (or tools) that can
help them detect when they are using features marked with these
- Even though semantic versioning rules don’t apply to unstable features, it is
recommended to bump a library’s minor version if unstable features have
- Tools are available to help identify accidental incompatibilities within a
major version. Examples:
- Examples of breaking changes to a public API that require a new major
- Upgrading to an incompatible dependency that is exposed through a
library’s public API. For dependencies that follow semantic versioning, this happens
when a dependency is bumped to a higher major version.
- Changing a method signature
- Removing a method (deprecated or not)
- Examples of additions that require a new minor version:
- Upgrading a dependency to a new minor version (compatible, but new
features) that is exposed through a library’s public API
- Adding a new class
- Adding a new method
- Special case: Maintainers do not have to increment a library’s major version when
a release is only to drop the support of an end-of-life Java version that is not widely used by
the consumers of the library.