|Re: [jakarta.ee-spec] [jakartaee-platform-dev] Semantic Versioning Jakarta APIs|
[EJ] Semantic versioning APIs to announce whether there are major or minor or no changes in the corresponding APIs.
Create package-info.java (see an example here) in the API packages
Using semantic versioning plugin bnd
Tooling to ensure that rules of semantic versioning are followed
Only in the class files to help the tooling (class retention annotations are runtime invisible)
Potentially an issue with the signature tests?
Since the annotations are added in the actual API jars, there should not be an issue with the signature tests
Is it ok to introduce a dependency to org.osgi.annotation.versioning.Version ?
What if the meaning of the annotation changes at a later stage?
Suggestion to create a Jakarta version of the OSGI version annotation(s) to have complete control over it?
Put them in the Jakarta Annotations project?
All other specs would then depend on Jakarta Annotations
Produce the artifact from e.g. the Platform project
No specification, just a well-documented “Build tooling project”
Or, use the org.osgi.* annotations?
MicroProfile use this tooling with success today
Marlow: TCK signature test could check specifically for org.osgi.* annotations that are not retained at runtime.
OSGi Semantic Versioning Whitepaper: http://docs.osgi.org/whitepaper/semantic-versioning/
_______________________________________________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.
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 APIsWe 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 versioningSemantic 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 versioningIn 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.
jakarta.ee-spec mailing list
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/jakarta.ee-spec
Back to the top