Re: [jakartaee-platform-dev] Semantic Versioning Jakarta APIs

[Emily Jiang <emijiang6@xxxxxxxxxxxxxx>]

Thank you Steve for you comments!

The semantic versioning is focusing on APIs/SPIs. It is absolutely fine for a spec to do a major release even if they are completely backward compatible with the previous version. As you have stated, the changes are significant and we should market it considerably. In this case, we can declare it a major release. Obviously, if a spec have backward incompatible changes, the spec should declare a major release which forces the platform to do a major release. This might not happen often in Jakarta EE as backward incompatible changes are rarely allowed.

Thanks

Emily

On Wed, Aug 25, 2021 at 11:15 AM Steve Millidge (Payara) <steve.millidge@xxxxxxxxxxx> wrote:

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

--

Thanks
Emily