[JLBP-3]

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 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:
  • Java API Compliance Checker
  • Clirr Maven Plugin
  • Java API Tracker: Compatibility report for grpc-core
• 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.