There has been some talk of relatively minor changes as a result of things being pruned from the platform.
Alasdair Nottingham On Nov 23, 2019, at 12:02 PM, Emily Jiang <emijiang6@xxxxxxxxxxxxxx> wrote:
My understanding for Jakarta EE9 is a simple namespace renaming from javax to Jakarta. I don’t recall the removal of deprecated methods is included. If we do this, surely the package version needs a major version bump. If no other changes are planned apart from package renaming, I think we should use the same version as javax. Thanks Emily > As mentioned in my previous comment, since Jakarta EE9 is to release all new APIs starting with jakarta. I think keeping the current counterpart version javax is better as it signify there is no other changes when compared to the counterpart. Also there are less changes.
This assumes no other changes will happen but now would be a good time to prune dead wood like getting rid of long deprecated methods. So I still think if the `javax` package version was 2.3, for example, we should version the replacement `jakarta` package with version 3.0 as in Kevin's excellent example.
> As for spec, artifact jar version, it is ok to use marketing version. I think using semantic version has some advantage as we can use it to signify whether there is a backward compatible changes in any APIs. You know, we can treat them as bundle versions.
Bundle versions and artifacts versions are basically the same thing. Long experience has taught me they need to be the same version so when I get an artifact from a repository it has the same internal version (bundle version) as the external version (artifact version). The is the least surprising.
Also applying semantic versioning to bundle/artifact versions does not work well in practice especially when you refactor the content of a set of artifacts. Code depends upon Java types which are contained in Java packages. Code does not really care what artifacts Java packages come from (although pom files do; but at runtime, there are no pom files...). And it is better to keep the artifact versions in sync with the spec versions which themselves are not semantically versioned.
--
BJ Hargrave Senior Technical Staff Member, IBM // office: +1 386 848 1781 OSGi Fellow and CTO of the OSGi Alliance // mobile: +1 386 848 3788 hargrave@xxxxxxxxxx
----- Original message ----- From: Emily Jiang <emijiang6@xxxxxxxxxxxxxx> Sent by: jakartaee-platform-dev-bounces@xxxxxxxxxxx To: jakartaee-platform developer discussions <jakartaee-platform-dev@xxxxxxxxxxx> Cc: Subject: [EXTERNAL] Re: [jakartaee-platform-dev] Continue semantic versioning discussion... Date: Fri, Nov 22, 2019 14:47
Hi BJ,
The initial version for each new Java package is, of course, free for us to choose. We have no requirement to use 1.0 and are free to use any version. So selecting an initial version for each new Java package based upon the history of the Java package it is replacing is a fine idea. It positions the new Java package in an evolutionary timeline relative to the Java package it is replacing. But it does make sense to use a higher major version than the major version of the Java package being replaced.
My main concern about versioning in Jakarta EE is that we can agree that going forward, we will semantically version the Java packages in the various specifications. Not about the specific initial version numbers we use for the renamed Java packages.
As mentioned in my previous comment, since Jakarta EE9 is to release all new APIs starting with jakarta. I think keeping the current counterpart version javax is better as it signify there is no other changes when compared to the counterpart. Also there are less changes.
As for spec, artifact jar version, it is ok to use marketing version. I think using semantic version has some advantage as we can use it to signify whether there is a backward compatible changes in any APIs. You know, we can treat them as bundle versions.
Thanks
Emily
There are several things that can be versioned.
Specifications, artifacts, and Java packages. (Note: When I say Java package here, I don't mean packages starting with 'java' or 'javax', I means Java packages as defined by the JLS.)
Specifications are things for humans to read. Their versions need to increase as we change/extend them. There is no practical need to semantically version specifications. They should use what I call "marketing" versions. You change the major or minor version of the specification to signal to the market the "size" of the change or otherwise create some desired marketing effect.
Artifacts are the things we build and put in repositories. API jars are the prime example here. Like specifications, their versions need to increase as we change them but there is no need, or practical way, to semantically version artifacts since they are aggregations of Java packages and the set of Java packages in an artifact may vary over time as new Java packages are added, Java packages are modified, or artifacts are refactored. So artifacts should also use "marketing" versions and should probably match the version of the specification to which they correspond. (I agree that there should be no -RELEASE type version suffix on the artifact version. Such suffixes are maven-isms.)
Finally we have Java packages. A Java package is a collection of Java types. The organization of Java types into Java packages is important. As we can see from JPMS and OSGi, Java packages are the units which can be shared with other modules. It is important for the users of the our Java packages that we maintain binary compatibility with past versions OR clearly indicate when we are not. So we should set it is a goal that we properly semantically version the Java packages in the Jakarta EE API to clearly signal to our users the Java package's binary compatibility.
Renaming a Java package, is a great way to signal a non-backwards compatible change. (Since we are renaming packages anyway, for non-technical reasons, this is a great opportunity to prune some deadwood :-)
The initial version for each new Java package is, of course, free for us to choose. We have no requirement to use 1.0 and are free to use any version. So selecting an initial version for each new Java package based upon the history of the Java package it is replacing is a fine idea. It positions the new Java package in an evolutionary timeline relative to the Java package it is replacing. But it does make sense to use a higher major version than the major version of the Java package being replaced.
My main concern about versioning in Jakarta EE is that we can agree that going forward, we will semantically version the Java packages in the various specifications. Not about the specific initial version numbers we use for the renamed Java packages.
-- BJ Hargrave Senior Technical Staff Member, IBM // office: +1 386 848 1781 OSGi Fellow and CTO of the OSGi Alliance // mobile: +1 386 848 3788 hargrave@xxxxxxxxxx
----- Original message ----- From: "Kevin Sutter" <sutter@xxxxxxxxxx> Sent by: jakartaee-platform-dev-bounces@xxxxxxxxxxx To: jakartaee-platform developer discussions <jakartaee-platform-dev@xxxxxxxxxxx> Cc: Subject: [EXTERNAL] Re: [jakartaee-platform-dev] Continue semantic versioning discussion... Date: Fri, Nov 22, 2019 09:02 In the words of Bill Shannon, let's put this "discussion to bed"... :-)
Thanks for the discussion. I also spoke with BJ (he brought up the item about the package versioning). He agreed that it was not necessary to reset the package version to 1.0.0. We can start the package versioning at any number. His main interest is that we continue to increment the versions according to the rules of semantic versioning. And, since we have stated our interest in that goal since the start, I think we're in good shape.
Based on all of this input, here's the proposal. I won't claim it's a "decision" until Tuesday's meeting since it was left over agenda item.
1. Spec level versioning. Due to the change from javax.* to jakarta.*, all of the individual Jakarta components will need to increase their major version for the Spec (x.y) and API (x.y.z).
Using JPA as an example, this would require a new entry in the maven repo for a 3.0.0 release of the API, which would have the following coordinates:
<!-- https://mvnrepository.com/artifact/jakarta.persistence/jakarta.persistence-api--> <dependency> <groupId>jakarta.persistence</groupId> <artifactId>jakarta.persistence-api</artifactId> <version>3.0.0</version> </dependency>
2. Package level versioning. The exported package names in the MANIFEST.MF should also be increased to the new major version.
Again, using JPA as an example, the MANIFEST.MF for JPA 3.0.0 would look something like this:
Export-Package: jakarta.persistence.metamodel;version="3.0.0",jakarta.persis tence;uses:="jakarta.persistence.criteria,jakarta.persistence.metamodel,jav ax.persistence.spi";version="3.0.0",jakarta.persistence.criteria;uses:="j akarta.persistence,jakarta.persistence.metamodel";version="3.0.0",jakarta.per sistence.spi;uses:="jakarta.persistence,javax.sql";version="3.0.0"
--------------------------------------------------- Kevin Sutter STSM, MicroProfile and Jakarta EE architect e-mail: sutter@xxxxxxxxxx Twitter: @kwsutter phone: tl-553-3620 (office), 507-253-3620 (office) LinkedIn: https://www.linkedin.com/in/kevinwsutter
From: "Kevin Sutter" <sutter@xxxxxxxxxx> To: "jakartaee-platform developer discussions" <jakartaee-platform-dev@xxxxxxxxxxx> Date: 11/19/2019 14:44 Subject: [EXTERNAL] [jakartaee-platform-dev] Continue semantic versioning discussion... Sent by: jakartaee-platform-dev-bounces@xxxxxxxxxxx
Hi, At the end of our Platform Dev call this morning, we started to discuss the versioning of the Jakarta Component specs due to the jakarta namespace update. As an example, with the jakarta package rename, should the next version of CDI be 2.x or 3.0? This was initially brought up as part of this thread: https://www.eclipse.org/lists/jakartaee-platform-dev/msg00862.html
The initial response on the call was "Yes", the major version of the CDI Spec must increase with the change in package names.
But, as we continued talking, it was clear there were two aspects (at least) of semantic versioning that come into play.
- Semantic versioning at the Spec level (ie. JPA 2.2 -> 3.0)
- Semantic versioning at the Package level (ie. javax.persistence.* -> jakarta.persistence.*)
1. Spec level versioning. I'm going to assume that the initial response is still accurate and we expect the individual Jakarta components to increase the major version of their Specs. Sticking with the JPA example, this would require a new entry in the maven repo for a 3.0 release, which would have the following coordinates:
<!-- https://mvnrepository.com/artifact/jakarta.persistence/jakarta.persistence-api--> <dependency> <groupId>jakarta.persistence</groupId> <artifactId>jakarta.persistence-api</artifactId> <version>3.0.0</version> </dependency>
This usage would allow proper dependency management at the macro level -- at the Spec and API level.
2. Package level versioning. This is what BJ brought up at the end of the call. As an example, look at the MANIFEST.MF for JPA 2.2.3:
Export-Package: javax.persistence.metamodel;version="2.2.3",javax.persis tence;uses:="javax.persistence.criteria,javax.persistence.metamodel,jav ax.persistence.spi";version="2.2.3",javax.persistence.criteria;uses:="j avax.persistence,javax.persistence.metamodel";version="2.2.3",javax.per sistence.spi;uses:="javax.persistence,javax.sql";version="2.2.3"
Since we're moving from javax.persistence.* to jakarta.persistence.*, this is technically a new API package and, thus, should start over at 1.0.0. A few questions come to mind here...
- If we claim we want to follow semantic versioning, does it require us to recognize this name change and start over at "1.0.0" with the package export? Or, can we decide that this change from javax to jakarta is just a continuation of the old package and use "3.0.0" for the jakarta.persistence.* packages?
- If it's decided that the jakarta.persistence.* package rename requires a "1.0.0", does it make sense to have different package versions from the external Spec/API version? In this case, the packages would be exported as "1.0.0", but the Spec would be at "3.0".
- Do we even care? Do any of the Jakarta components currently import packages with specific version numbers? The JPA MANIFEST just imports the package names with no versions. I know this comes into play with an OSGI-based system (we use both export and import packages with versions in Open Liberty, for example). But, do we need or want to incorporate that level of dependency mgmt on everyone using Jakarta EE?
I have my thoughts on what we should do, but let's start with the discussion first. Thanks.
--------------------------------------------------- Kevin Sutter STSM, MicroProfile and Jakarta EE architect e-mail: sutter@xxxxxxxxxx Twitter: @kwsutter phone: tl-553-3620 (office), 507-253-3620 (office) LinkedIn: https://www.linkedin.com/in/kevinwsutter_______________________________________________ jakartaee-platform-dev mailing list jakartaee-platform-dev@xxxxxxxxxxx To change your delivery options, retrieve your password, or unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/jakartaee-platform-dev
_______________________________________________ jakartaee-platform-dev mailing list jakartaee-platform-dev@xxxxxxxxxxx To change your delivery options, retrieve your password, or unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/jakartaee-platform-dev
--
_______________________________________________
jakartaee-platform-dev mailing list
jakartaee-platform-dev@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://www.eclipse.org/mailman/listinfo/jakartaee-platform-dev
_______________________________________________jakartaee-platform-dev mailing listjakartaee-platform-dev@xxxxxxxxxxxTo change your delivery options, retrieve your password, or unsubscribe from this list, visithttps://www.eclipse.org/mailman/listinfo/jakartaee-platform-dev
|