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
