Re: [jakartaee-platform-dev] Continue semantic versioning discussion...

["Kevin Sutter" <sutter@xxxxxxxxxx>]

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.

1. Semantic versioning at the Spec level (ie. JPA 2.2 -> 3.0)
2. 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