Date: 27.01.2020
@since
in javadoc: 21.02.2020accepted
Eclipse Ditto project exited the incubation phase with release 1.0.0. Henceforth, any change to the Ditto API enters a Ditto release according to semantic versioning:
This document defines what API compatibility means, the modules which are considered API and for which semantic versioning holds, and the enforcement of semantic versioning.
For Eclipse Ditto, API compatibility means binary compatibility defined by the Java Language Specification, Java SE 8 Edition, chapter 13. Examples of binary-compatible changes:
Binary compatibility guarantees that any user code of Ditto does not break on minor version upgrades, provided that
Inheritance from Ditto classes and interfaces is excluded from API compatibility because Ditto interfaces are often defined to hide implementation details from user code. Compatibility for user-defined subclasses, or source compatibility, is not a part of Ditto's semantic versioning. Inheriting user classes may break after a minor Ditto version upgrade.
Public classes, interfaces and their public members of the following modules, and their submodules are considered Ditto API. Changes to them must enter Ditto release in accord with semantic versioning. Modules not on this list are not considered API; they may contain incompatible changes for any Ditto version change.
ditto-json ditto-base-model ditto-messages-model ditto-jwt-model ditto-rql-model ditto-rql-query ditto-rql-parser ditto-policies-model ditto-things-model ditto-thingsearch-model ditto-concierge-model ditto-connectivity-model ditto-protocol ditto-utils
@since
When adding new public visible API (e.g. new interfaces, classes or methods in existing code) in the defined API modules, a @since <version>
javadoc annotation shall be added.
Example:
/** * Returns the extra information which enriches the actual value of this change. * * @return the extra data or an empty Optional. * @since 1.1.0 */ Optional<JsonObject> getExtra();
Existing public API without @since
can be interpreted as @since 1.0.0
and can be added when adjusting a class.
Semantic versioning is enforced through binary compatibility check by japicmp-maven-plugin
.
<plugin> <groupId>com.github.siom79.japicmp</groupId> <artifactId>japicmp-maven-plugin</artifactId> </plugin>
Deviations of the behavior of japicmp-maven-plugin
from binary compatibility defined by the Java language specification are to be corrected through overrides. If japicmp-maven-plugin
breaks the build for a branch, then a major version increment for the next release is required to merge the branch into Ditto master. Check with the whole Ditto team before adding anything to the exclusion list of japicmp-maven-plugin
.
User code of modules considered API does not break on minor Ditto version upgrade if it does not inherit from Ditto classes or interfaces.
User code of modules considered API does not break on patch Ditto version upgrade.
User code of other modules may break on any Ditto version change.