| Re: [jakartaee-platform-dev] Semantic Versioning Jakarta APIs |
|
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.
-- Thanks
Emily |