Does updating Spec APIs' Java compile level lead to a major or minor release?

[Emily Jiang]

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.

on c

--

Thanks
Emily

[Scott Stark]

While that is true from a strictly technical need to change code point of view, it still has a major impact when it comes to deploying applications. The toolchain needs to be updated, base images in containers need to be updated, etc., etc. There definitely were various little things that made a switch from SE 8 to 11 a nontrivial effort for the build and productization teams, so I would certainly expect this to be reflected as a major change

[John Clingan]

Good point.

--
You received this message because you are subscribed to the Google Groups "MicroProfile" group.
To unsubscribe from this group and stop receiving emails from it, send an email to microprofile...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/e475481e-211b-472f-99e2-176634d0b1c9n%40googlegroups.com.

[Emily Jiang]

Just forward the message from BJ as his email to the mailinglists were bounced back.

Thanks

Emily

On Wed, Nov 22, 2023 at 6:43 PM BJ Hargrave <harg...@us.ibm.com> wrote:

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
harg...@us.ibm.com

 

 

 

From: Emily Jiang <emij...@googlemail.com>
Date: Wednesday, November 22, 2023 at 12:57
To: Microprofile WG discussions <micropr...@eclipse.org>, MicroProfile <microp...@googlegroups.com>
Cc: BJ Hargrave <harg...@us.ibm.com>
Subject: [EXTERNAL] Does updating Spec APIs' Java compile level lead to a major or minor release?

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

--

Thanks
Emily

[Emily Jiang]

We discussed this issue again at the MP Technical call on 13th Feb. As you might know. the semantic versioning plugin can work out correctly regarding the package versions. The API  jar version is the aggregation of the package version, as shown blow (quote from here)

The version of a bundle must therefore semantically aggregate the semantics of all its constituent packages. If any of these packages are incompatible with its providers then the bundle version must increment the minor version. If any of these packages are incompatible with consumers, the bundle version must increment the major version. It is clear, that on average, the version of a bundle will be much more volatile than the versions of its constituent packages, increasing the dependency problems.

It is important we adopt the semantic versioning policy for packages and the whole jar.

Based on the semantic versioning policy, updating Java version is not a major version update as it has no direct package semantic impact. Adopting on Jakarta EE 10 might not need to bump the major version of the MicroProfile specifications if no major version changes on any of its packages.

I understand some specifications did not want to perform a major release just to compile with Java 11 and align with Jakarta EE 10. Hope this solves that concern.

We will discuss this again in the next Live Hangout and settle this issue. At the moment, it blocks the MP 7.0 plan review.

Thanks

Emily

--

Thanks
Emily