| Re: [microprofile-wg] Does updating Spec APIs' Java compile level lead to a major or minor release? |
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