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 public and protected surface of a
1.0 or later library is considered to be stable API.
- Annotations can mark features (classes, methods, etc.) as unstable
so that semantic versioning rules do not apply.
- Examples of annotations:
- Guava uses
@Beta
- grpc-java uses
@ExperimentalApi
- Google-cloud-java uses
@BetaApi, @InternalApi, and @InternalExtensionOnly
- Library documentation should point users to a tool (or tools) that can
help them detect when they are using features marked with these
annotations.
- 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
surface breakages.
- 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
version:
- 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)
- Adding a method to an interface without a default implementation
- Adding an abstract method to a class
- 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 only drops support for an end-of-life Java version that is not widely used by
the consumers of the library.