Semantic versioning can see both new backwards-compatible changes (minor version increment) as well as new backwards-incompatible changes (major version increment).
The value of the tooling here is to clearly distinguish between the two. General we are improving a specification by adding new features and thus generally expect minor version increments. And we want to correctly capture this in the metadata. But sometimes the change is backwards-incompatible without being readily noticed by the developer. For example, adding a new (non-default) method to an interface which the API users are expected to implement.
In the case were a change is considered a major version change by the tooling but the specification developers, in their wisdom, would rather only declare the change to be minor, an annotation can be used to advise the tool to not consider that change as a versioning error during baselining.
Semantic versioning works well for Java packages which are (and should be) focused and cohesive units. The tooling is focused on the semantic versioning of Java packages. Aggregates of packages, such as jar files, are not well suited to semantic versioning since the contents of the aggregate can change from time-to-time as Java packages may move to different aggregates. This can happen when splitting or combining jars. Sometime a Java package can exist in multiple aggregates (like uber-jars and the specification API jar). I suggest we do not attempt to apply semantic versioning to aggregates. Just to Java packages.
--
BJ Hargrave
Senior Technical Staff Member, IBM // office: +1 386 848 1781
OSGi Fellow and OSGi Specification Project lead // mobile: +1 386 848 3788
hargrave@xxxxxxxxxx
----- Original message -----
From: "Steve Millidge (Payara)" <steve.millidge@xxxxxxxxxxx>
Sent by: "jakartaee-platform-dev" <jakartaee-platform-dev-bounces@xxxxxxxxxxx>
To: "jakartaee-platform developer discussions" <jakartaee-platform-dev@xxxxxxxxxxx>, "Jakarta specification discussions" <jakarta.ee-spec@xxxxxxxxxxx>
Cc:
Subject: [EXTERNAL] Re: [jakartaee-platform-dev] Semantic Versioning Jakarta APIs
Date: Wed, Aug 25, 2021 06:15
My personal view is semantic versioning only focuses on one aspect of change i.e. breaking changes. It does not provide any information on whether a new api is significantly enhanced but without breaking changes and therefore worth a closer look by a developer. It can also force a "major" release for a minor incompatibility which may not be relevant to the majority. While this is intellectually pure it is also anaemic.
Saying that, if we don't fall into the trap of using semantic versioning for the overall platform then we may get away with it.
Steve
From: jakartaee-platform-dev <jakartaee-platform-dev-bounces@xxxxxxxxxxx> on behalf of Emily Jiang via jakartaee-platform-dev <jakartaee-platform-dev@xxxxxxxxxxx>
Sent: 24 August 2021 10:14 PM
To: jakartaee-platform developer discussions <jakartaee-platform-dev@xxxxxxxxxxx>; Jakarta specification discussions <jakarta.ee-spec@xxxxxxxxxxx>
Cc: Emily Jiang <emijiang6@xxxxxxxxxxxxxx>
Subject: [jakartaee-platform-dev] Semantic Versioning Jakarta APIs
We discussed in today's Jakarta platform call regarding semantic versioning Jakarta APIs(see minutes
here). The discussion was positive. Since this impacts all specifications, we would like to see what others think.
Some context on Semantic versioning
Semantic versioning is to version each individual API package. Refer
this white paper to understand semantic versioning. MicroProfile has been using semantic versioning to version the APIs from the beginning and it helped the specifications a great deal when deciding whether to perform a major or minor release. In Jakarta EE, specs are cautious with backward incompatible changes. However, no building tool is used to validate whether a particular spec has introduced such changes.
With semantic versioning, both implementers and end users have a clear view on what APIs changes are introduced between releases. If the version for a particular package stays the same between the releases, it means no changes are introduced for that package. If major version changes (e.g. the version changes from 1.0 to 2.0), it means backward incompatible changes are introduced between the releases.
How to do semantic versioning
In each API package, you just need to create a package-info.java with the version number (see an example
here). You can also use this package-info to log the javadoc for that particular package. There are a couple of maven plugins to process the package version and then do the version comparison. Again, MicroProfile has the full set up to get it working. It is just a copy and paste job in the pom.xml when getting semantic versioning implemented in Jakarta EE specs.
If you have any questions, please feel free to comment here.
