Skip to main content
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [jakartaee-platform-dev] [jakarta.ee-spec] Semantic Versioning Jakarta APIs
Hi Emily,

Thanks for bringing this up on the mailing list.
We've been discussing versioning often during the last few weeks and could have saved some time if we would start the thread before.

Better late than never, so thank you again :-)

Thanks Steve as well, I think I agree with your view.
I'm ok if we can support semantic versioning but I am very cautious about the way we want to implement it.

Follow up on the discussion last Tuesday and the minutes

  • [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
          or

        • 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/




Adding OSGi annotation dependency in APIs would require all signatures to be updated as well so we can check them.
What happens for other spec jars?
At Apache, there are API jars for pretty much all specifications. Adding to signature tests would require all apache API jars to be updated to add that OSGi annotation as well.

I'm not ok with adding an OSGi dependency and I'm not ok with the impact on the community.

Class retention: even if it's class retention it's still in the bytecode.
Deployment does not always happen at runtime (Quarkus for example).
And it's not uncommon to use tools like ASM, javasist, or other to read the bytecode where this annotation could be used for something specific, seriously impacting portability.

Do we want to open that door?
If we add OSGi Version annotation, why don't we add others?

That being said, let's step back a bit.
Let's say we want a semantic versioning in Jakarta for our APIs. First we would need to discuss and decide on the mailing list.
I would recommend not mixing with the "how to do it?"

On the "how", it looks like all the @Version with OSGi discussion comes from the tool we want to use (BND).
If the tool does not fit with our requirements, let's use/write another one.
A tool should help and not be a restriction.

Throwing a crazy idea to illustrate. Not saying it's good and we should follow this path.
We have had signature tests with signature definitions for ages.
Why don't we write a tool that does a comparison with a previous version of the signature definition?

Brainstorming but hope it helps




On Wed, Aug 25, 2021 at 12:15 PM 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

_______________________________________________
jakarta.ee-spec mailing list
jakarta.ee-spec@xxxxxxxxxxx
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/jakarta.ee-spec

Back to the top