The Jakarta EE 9 release plan mentions semantic versioning at the package level as a goal. This is a good goal to have but it is hard for humans to get this right without assistance from tools.
The subject at hand is to use such tooling to manage semantic versioning discipline for the packages in the API artifacts. This is done via class-retention annotations in package-info source and (sometimes) in class source when it is necessary to distinguish the role of a type [1] and build tooling which understands the class-retention annotations to generate metadata in the artifact and compare the built artifact against previously released artifacts (baselining) to detect semantic versioning mistakes.
There are a number of consumers of the Jakarta artifacts which need proper OSGi metadata. It is better for all when the upstream project includes this otherwise downstream consumers must repackage the API artifacts and attempt to divine the intentions of the upstream developers.
You may not care about OSGi and, of course, you do not need to use OSGi, but others in the Jakarta community do including the OSGi Specification Project, also at Eclipse, which will need to support the new jakarta.* namespace APIs in the coming year. Since both Jakarta EE and OSGi are peer projects at Eclipse now, I would like it if we can support each other in the success of both project families.
There has been discussion of the creation of Jakarta semantic versioning annotations (as analogs to the existing OSGi annotations) for this same purpose. When (and if) these Jakarta semantic versioning annotations are created and the tooling is taught about them, we can replace the use of OSGi annotations in the Jakarta projects. But for now, we should start with what exists to help the Jakarta EE API artifacts have proper semantic versioning and to support downstream consumers who do need OSGi metadata.
[1]: consumer vs. provider role: is the application expected to implement the interface, for example a listener, or is the application only expected to use the interface
--
BJ Hargrave
Senior Technical Staff Member, IBM // office: +1 386 848 1781
OSGi Fellow and OSGi Specification Project lead // mobile: +1 386 848 3788
hargrave@xxxxxxxxxx
----- Original message -----
From: "Emily Jiang" <emijiang6@xxxxxxxxxxxxxx>
To: "Ladislav Thon" <lthon@xxxxxxxxxx>, "BJ Hargrave" <hargrave@xxxxxxxxxx>
Cc: "cdi developer discussions" <cdi-dev@xxxxxxxxxxx>
Subject: [EXTERNAL] Re: [cdi-dev] Any opposition to exploring semantic versioning via OSGi annotations?
Date: Sun, Dec 12, 2021 16:38
> If I recall correctly, some MicroProfile specifications had troubles with keeping those annotations up to date, I am not sure what you meant. I tried to keep the plugin up to date. Besides, as long as the plugin does the job, it is good ZjQcmQRYFpfptBannerStart
This Message Is From an External Sender
This message came from outside your organization.
> If I recall correctly, some MicroProfile specifications had troubles with keeping those annotations up to date,
I am not sure what you meant. I tried to keep the plugin up to date. Besides, as long as the plugin does the job, it is good enough. Once it is in place, you don't need to update it. It will keep running and break the build if any backward incompatible changes got it without acknowledging with the major version changes.
I don't think not understanding it is a valid reason to ignore it. It is pretty straightforward to grasp it if people are willing to learn. I am sure BJ on cc can do a talk on it.
Tangent: if there's a spec (such as Transactions) struggling to figure out the impact of CDI's breaking changes, they should reach out to CDI. I'm sure we'd be glad to help. (My hunch is that they're not affected at all, because the only thing from JTA that depends on CDI is @Transactional and @TransactionScoped, but I didn't really look.)
It is true to talk to a different community to learn more. However, if the artifacts can be self explanatory, it is much more scable. Besides, for figuring out backward incompatible changes, I am afraid it is not trivial sometimes.
Emily
I'm not a fan myself either. If I recall correctly, some MicroProfile specifications had troubles with keeping those annotations up to date, and I'd guess that's because 1. [almost] no one actually remembers the annotations are there (I know I don't), 2. [almost] no one actually understands how to use them (I know I don't). I'm pretty sure the exact same thing is going to happen to CDI soon after the prototype is successfully finished and deployed. Plus I'd say that for CDI, package-level granularity is too coarse. I'm even going to claim that package-level versioning gives virtually zero benefit over artifact-level versioning (at least in case of CDI). There are tools out there (such as
https://revapi.org/) that can actually help with tracking compatibility and breaking changes, but annotating packages is not it.
Tangent: if there's a spec (such as Transactions) struggling to figure out the impact of CDI's breaking changes, they should reach out to CDI. I'm sure we'd be glad to help. (My hunch is that they're not affected at all, because the only thing from JTA that depends on CDI is @Transactional and @TransactionScoped, but I didn't really look.)
LT
The annotations can be only on package-info.java not on any of the APIs if the packages are consumer/provider type. Besides they are only build time annotations and we mark the dependency type as "Provided".
Thanks,
Emily
Still not a fan of incorporating OSGi annotations in any of our APIs.
So one of the goals of the platform is to introduce a stronger semantic versioning model. The general issue and associated platform dev thread is captured in this issue:
BJ Hargrove of the Open Liberty team and OSGi working group volunteered to explore what an update of the CDI artifacts to make use of the OSGi artifacts would entail. There is no point in doing this if we have a hard stance about introducing a build time only dependency on the OSGi annotations. There is an ongoing discussion about potentially introducing a similar set of annotations in Jakarta, but any current prototype effort would have to be based on the OSGi library.
Thoughts?
_______________________________________________
cdi-dev mailing list
cdi-dev@xxxxxxxxxxxTo unsubscribe from this list, visit
https://www.eclipse.org/mailman/listinfo/cdi-dev
cdi-dev mailing list
cdi-dev@xxxxxxxxxxx
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/cdi-dev
--
_______________________________________________
cdi-dev mailing list
cdi-dev@xxxxxxxxxxx
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/cdi-dev
--
