Java – Maven: Versioning for multi module repository

javamavenrelease-managementversioning

Versioning is always a big question and I see many similar questions here, however none really answer my question so I try to highlight the things that are important to me specifically.

We have a single repository for a multi-module maven project. The decision for a single repository was made, because the modules are (in part) tightly coupled, and it makes refactoring across the whole codebase easier. The move to a monorepo was done just recently without thinking about how to properly handle versioning and releases.

Before, each module (then a separate project in a separate repository) was released independently and luckily never introduced breaking changes, so customers could freely choose which versions to use and never had any issues.

What I want to do is keep offering releases for the individual modules, because it makes updating much easier. (Bugfix release? just exchange the jar file). But I always want to release distribution packages.

Consider the following layout:

pom.xml
  --- app1 pom.xml
  --- app2 pom.xml
  --- lib1 pom.xml
  --- dist pom.xml

Each module has its own version. An application might get a new feature which justifies a bump in the minor version, a library might get constant buxfixes so its micro version increases fast.

It comes down to two questions:

  • Under these circumstances – what is the meaning of the version number of the maven root project?

I could imagine it simply tracking the state of the repository. A new module is added? Bump the micro version. A module is removed/merged? Bump the major version. Things like that. But I'm not sure if this is a good approach.

  • What version should the distribution package have?

When all components have different versions, I just can't pick a single one. Every update of the components has to be reflected in the distribution's version. Although I really like semantic versioning, I feel like a date-based approach might be better suited here. Make a distribution release every 6 months or so and call it 2020_06. If an important bugfix required the update of a component in between, a version like 2020_06.2 might work as well.

Best Answer

First of all, you're mixing two things that are completely independent from each other:

  • (One for all or one for each) SCM repository and
  • Maven projects with their versioning.

Note that sub-module projects that use a <parent> don't necessarily have to use the parent POM version that's the current one in the SCM repository, e.g.:

Root POM

  <groupId>my</groupId>
  <artifactId>root</artifactId>
  <version>2.0.0-SNAPSHOT</version>

Lib1 POM

  <parent>
    <groupId>my</groupId>
    <artifactId>root</artifactId>
    <version>1.2.3</version>
  </parent>

  <groupId>my</groupId>
  <artifactId>lib1</artifactId>
  <version>4.5.6-SNAPSHOT</version>

is perfectly fine since my:root:1.2.3:pom will be resolved from the (local or remote) Maven repository (if it has been installed/deployed there previously).

Root Project Version

The meaning of the version number of the root project (with <packaging>pom) is the same as for any other Maven project:

  • x.y.z-SNAPSHOT version while you add/remove/change things in your POM and test them,
  • x.y.z release version if every work is finished, tested thoroughly and hence ready to be released into the wild.

It's entirely up to you which change increases the major, minor or patch version number. As a first approach I'd change the major version for changes that cause builds to fail potentially (e.g. if it's not clear whether an upgraded dependency version is downwards-compatible) or even definitely (replacing JUnit4 with JUnit5, for instance). I'd change the minor version for e.g. a version upgrade of a dependency that's proven downwards-compatible. I'd change the patch version if it turns out that the tests weren't that thorough after all and there's e.g. a typo or a misconfiguration of a plugin, or the like. (See also Semantic Versioning 1.0.0 and 2.0.0)

Distribution Package Version

You don't have to pick a version from (one of) the components. The things mentioned at the beginning (independence of SCM repository and Maven projects) and under Root Project Version above apply here, as well.

Related Topic