[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
Re: [microprofile-wg] Does updating Spec APIs' Java compile level lead to a major or minor release?
|
Hi,
I think we all agree to be compliant to
Semantic Versioning (semver) because it's very useful, as it
offers a simple human and machine readable technical contract
description.
We also agree on the fact a breaking change is requiring a Major
Release then.
I looks like we disagree what is a
breaking change, what semver requires and how the system
environment is defined.
@Emily: First, as BJ mentioned too,
it's not a technical requirement to update the Java compile level
in any case, in most cases it can stay on it's original compile
level.
But to make it transparent, if the
there is a constraint like a raise of the Java SE minimum version
(from the source (of the component itself or one of it's
dependencies), then it should be bumped to that new minimum
version to make this fact transparent to consumers (and it should
be recompiled for that level).
A change from Java SE 8 to Java SE 11
minimum version for compiling and including running a dependent
application is a breaking change on my perspective and therefore
requires a Major Release to be compliant with semver.
Unfortunately this is not that clear,
as Java SE versions do not follow semver at all, but it contains
breaking changes like the byte code level and supported platforms
in this case. I.e. when you run your app on a Sun Spark Java SE 8
JVM, after this change has been done, you can not run it anymore,
as there is no (at least public open source) JVM with support for
11 available. As a user, this change is not expected to happen on
a Patch or Minor Release.
In general we can expect Java SE is
doing breaking changes between LTS releases for relatively sure.
@BJ: Semver is not focusing on the
software component API only, it's focusing on the outside
technical contract at all.
So think of the Java SE API and impact
of the JVM in a JRE or JDK on it's OS and hardware architecture
too, which defines the narrower to outer System Environment.
Users need to reflect that, as you
mentioned already - it's part of the technical contract that is
covered by semver and changes need to be transparent to users.
Depending version changes on the fact
it requires recompilation only is ignoring the system environment
constraint changes and therefore not enough here,
So I agree with Scott, this must be
make transparent and reflected in the Major Release in this case.
If a component depends on a component that requires a higher Java
SE version to run it, then this should be reflected in it's own
Java SE version too, as it otherwise hides that circumstance for
the user that wants to run it. Also the version numbering should
reflect this breaking behaviour. Otherwise a so called hidden link
is created instead, when looking from the Systems Engineering
point of view.
A simple example:
Component A 1.0.0 (-> Java SE 8)
depends on
Component B 1.0.0 (-> Java SE 8)
Now in B the Java SE minimum version is updated, which has
(hidden) impact on A:
Component A 1.0.0 (-> Java SE 8, but runs on Java SE 11+ only)
depends on
Component B 2.0.0 (-> Java SE 11)
Note: When use something like Maven for
the dependency management, then A needs a version update too to
reflect it points to that new dependency version of B.
Updating A makes dependency
transparent:
Component A 2.0.0 (-> Java SE 11)
depends on
Component B 2.0.0(-> Java SE 11)
This is true for the following similar
relations:
component spec API A -> component
spec API B
user application -> component spec
API -> implementation
component spec A TCK -> component
spec A API
component spec -> parent
parent -> test dependency
For the last variant we had a recent
example:
MP Parent 2.8/TCK BOM (-> Java SE
8)
depends on
TestNG 7.5.1 (-> Java SE 8)
and
MP Parent 3.2/TCK BOM (-> Java SE
11)
depends on
TestNG 7.8.0 (-> Java SE 11,
breaking change in a Minor Release!)
Note: Another requirement of semver is
a three part version number at minimum, but let's ignore this
here.
When you try to do the following with
the expectation of semver allowing this, this let component spec
TCKs fail, that depend on a Java SE 8 runtime:
MP Parent 2.8/TCK BOM (-> Java SE 8,
but runs on Java SE 11+ only)
depends on
TestNG 7.8.0 (-> Java SE 11)
In fact, TestNG is violating semver
with their Minor Release only in this case. Downgrading the update
of TestNG to 7.5.1 solved the issue for the MP Parent 2.8 Minor
Release at the end.
We should do it better and do a Major
Release in such a case, in the interest of our users that do not
want to dig into details but just wanted to get their expectations
fulfilled by the version numbering. Also tools will be able to
depend on it too.
BTW, with doing a Major Release, then
component specs have also the opportunity in the future to do a
backport of features from the current to the former Major Release
as a new Minor Release there without violating semver.
Best,
Jan
PS: We have the same issue in Jakarta
EE too, including the upcoming Java EE 11 Platform Release (i.e.
in the planed Jakarta Validation Minor Release for it).
Am 22.11.23 um 23:26 schrieb Emily
Jiang via microprofile-wg:
Just forward the message from BJ as his email to the
mailinglists were bounced back.
Thanks
Emily
When
talking about versions here, I am discussing the
semantic version of the API. Semantic versioning
of an API is about communicating important
information about the API to the clients of the
API.
A
semantic version does not include implementation
details of the API. So, for an API jar having some
small implementation details (e.g., exception
classes), changes to these implementation details
do not constitute a semantic change to the API.
Even when such an implementation detail adds a new
dependency (e.g. depending on a json parser impl)
or changes a dependency (e.g. from one json parser
impl to a different json parser impl), this still
does not constitute a semantic change to the API
and thus there is no major or even minor version
increment warranted.
A
change in the implementation details of an API jar
does not require clients of the API to change in
any way. The clients do not need to be recompiled.
The client binaries will run, without change,
using the changed API jar. Of course, all
implementation dependencies need to be met at
build time and runtime. e.g., the necessary json
parser jar must be present.
The
same is true for a minor version increment. This
communicates that a client does not need source
changes or to be recompiled to use the updated
API.jar.
A
major version increment communicates that the API
is now so semantically different, that clients
cannot use the API jar without source changes
which necessitate a recompilation.
Class
file versions are implementation details. Changing
the class file versions of the classes in an API
jar does not result in any semantic changes to the
API. It just changes the implementation dependency
of the API jar to a different Java version. Every
jar in a build and at runtime has an
implementation dependency on a Java version. To
build and run, you must meet the highest Java
version dependency. Client code does not need
source changes or to be recompiled to use the
updated API jar which may depend up on a higher
Java version than the client code.
So,
making a major version increment to the API jar’s
semantic version just because the API jar’s
implementation dependency on the Java version
changes is communicating faulty information to
clients since clients need zero changes to use the
updated API jar. Existing client binaries will run
against the updated API jar at runtime provided
the Java version dependencies of all jars in the
runtime are met. If you want to recompile the
client (without any other changes) using the
updated API jar, then you will also need to make
sure that the Java version dependencies of all
jars in the build are met.
Of
course, if this discussion is not about
semantically versioning APIs, then never mind.
😊
BJ Hargrave
Senior Technical Staff Member, IBM // office:
+1 386 848 1781
Open Source Development // mobile: +1 386 848
3788
hargrave@xxxxxxxxxx
In
preparing for MP 7. 0, some specifications
such as MicroProfile Health would like to
adopt Jakarta EE 10 Core Profile and consume
the latest mp-parent pom 3. x to use the
latest plugins such as TestNG 7. 8. 0, which
also requires Java 11+. This
In preparing for MP
7.0, some specifications such as
MicroProfile Health would like to adopt
Jakarta EE 10 Core Profile and consume the
latest mp-parent pom 3.x to use the latest
plugins such as TestNG 7.8.0, which also
requires Java 11+. This means that the
project has to update the Java compile
level from Java 8 to Java 11.
On this week's MP
technical call, it was suggested that such
a change should lead to a MAJOR version
release as it drops Java 8 support. I
mentioned on the call that BJ on cc
explained in the past that this is NOT a
major change but a minor change as the
APIs have not changed at all. I had a chat
with BJ earlier and he explained that this
Java version change was an implementation
detail and did not force the end users to
recompile their code. I let BJ explain in
more detail. Please comment if you think
otherwise.
--
_______________________________________________
microprofile-wg mailing list
microprofile-wg@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://www.eclipse.org/mailman/listinfo/microprofile-wg
