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.
