Rules about versioning GlassFish and GlassFish project components (HK2, Grizzly, etc.)

[OndroMih]

Hi, fellow GlassFish committers,

I'd like to bring this point after coming across this issue raised for HK2: eclipse-ee4j/glassfish-hk2#888

The issue is that versioning of releases and upgrading dependencies is sometimes taken lightly, without much consideration. Often dependencies suggested by dependabot are routinely merged and new component releases often just increase a patch version where they should increase a minor or major version.

I want to start this discussion to align on some simple rules about merging dependencies, introducing breaking changes, and versioning. Especially for components like HK2 or Grizzly, because I think we already handle this well in the main GlassFish repository.

I suggest the following to consider:

• if a merge request updates not only the patch number but the minor or major number - either increase the minor or major number for the GlassFish component itself (e.g. change 1.2.3-SNAPSHOT to 1.3.0-SNAPSHOT), or change the merge request to upgrade only to the latest patch version and defer bigger upgrades to a new version branch
• During a release, we should check whether any dependency upgrade increases minor or major version number, and if the snapshot version is not already increased accordingly, increase the minor or major number for the new release, instead of just increasing the patch number
• dropping support for an old Java version number should be considered at least a minor change, or even a major change, not a patch

What do others think?

Can we introduce some maven plugin that ensures some of these rules? Does anybody know about such a plugin?

Ondro

[dmatej]

I believe it was resolved long ago, there are also general standards about it.
Yes, this mistake in HK2 happened, and as nobody created a PR to fix it, time went by.

Upgrading Dependencies

• Breaking changes should be detected by our tests first.
• Increasing major version usually means some risk, but not always. It is always something to consider - some dependencies touch Jakarta EE compliance (eg anything jakarta.*), some don't (eg. JSch).
• Increasing minor version should be safe, however sometimes it still break something. Again, tests should detect it. (eg race conditions, dependency on Unsafe whatever)
• Patch versions should be safe, it is sad, but it is not always true.
• In all cases we should also always check release notes - and we usually add them to the issue description as links.
• Doing that on a release date is too late, it must be done when doing a review.

Releasing

• Part of any review is to think about breaking changes.
  • In libraries like HK2 it is simplier as it is mostly a matter of API.
  • In GlassFish it is harder as API is mostly defined by Jakarta EE specs, and just some things are relevant (eg. asadmin command arguments, user experience).
• In HK2 in the past - there was some chaos when we expected release of different version id, then there were issues with OSGi and build system, then PRs were merged in different order than expected, and the result was releasing patch with breaking changes.

Since Then

• We started adding release notes to every update PR (if we don't forget)
• Dependabot does it automatically.
• Important changes are added also to our release notes (we should improve it a bit, probably)
• We are slowly cleaning up the dependency tree
• We improved OSGi so now it is mostly automated, just few places can need manual changes and those are reported in tests and logs.

TODO

• If I remember well, the maven dependency plugin can report transitive dependencies which are directly used by your project, but not declared - and exactly opposite, when you declare a dependency which you don't directly use. It is considered as a bug. However it is not so easy, we still have to do a lot of cleanup.
• I believe we will make it in GF8, however there is a trap - some GF classes are hardcoded in other applications including TCK, so on the background I am making notes. We can make them deprecated and then point to a replacement.