Thursday 25 January 2024

Five Element Maven Version Numbering System (N5)

Five element unique

The Five Element Maven Version Numbering System (N5) addresses the problem of wack-a-mole Maven dependency management: through the combination of excessive modularisation, microservices fervour, XML Declarative Project Object Models and non-unique (SemVer) versioning enterprise Maven Java projects become unmanageable after about five years.

The solution is a sequential identifier which is unique across the space, and does not require xml parsing to modify.

My first three proposals represent blundering steps towards the N5 Maven Version numbering system.

N5 Unique Versioned Artifact Identifier (Maven version)

\dCode for project
\d\d\dCode for repository
\d+Major
\d+Minor
\d+Patch

The previous version, N6, included the Year between the Repository Code and the SemVer Major Version. This was considered too much.

2.130.2.0.6 works well with the Maven tooling and can be updated over the whole space using sed.

Friday 19 January 2024

Maven Version Versions and a Regex Block Refactoring of Sequential Identifier

In the first post in this series I had thought about the need for a globally unique incrementable artifect id, in the next post I not only designed but tested a proposal for such a globally unique artifact id and how to change it.

A triumph of thought and testing over trial and error.

So I tried using the new scheme with the Maven Release Plugin.

A depressing journey into the rabbit hole that is Apache, Maven and the Release Plugin, a crucial tool in our pipeline.

It turns out that whilst the Maven Artifact Version I had tested against allowed my new scheme the Release Plugin has its own subset of such versions which are gate-kept by a Regular Expression.

          "^((?:\\d+\\.)*\\d+)" // digit(s) and '.' repeated followed by digit (version digits 1.22.0, etc)
                    + "([-_])?" // optional - or _ (annotation separator)
                    + "([a-zA-Z]*)" // alpha characters (looking for annotation - alpha, beta, RC, etc.)
                    + "([-_])?" // optional - or _ (annotation revision separator)
                    + "(\\d*)" // digits (any digits after rc or beta is an annotation revision)
                    + "(?:([-_])?(.*?))?$"); // - or _ followed everything else (build specifier)

This stops any version which does not start with digits and full stops from being recognised as a version.

Current Incremented Outcome
VTW360-2023-1.0.3-SNAPSHOT Unable to parse the version string F
VTW360.2023.1.0.4-SNAPSHOT Unable to parse the version string F
VTW360-2023.1.0.4-SNAPSHOT Unable to parse the version string F
VTW-360-2023.1.0.14-SNAPSHOT Unable to parse the version string F
VTW-360.2023.1.0.16-SNAPSHOT Unable to parse the version string F
2023-VTW360-1.0.3-SNAPSHOT 2023-VTW361-1.0.4-SNAPSHOT Eh?
2023|VTW-360|1.0.14 Illegal characters in jar name F
2023#VTW-360#1.0.14-SNAPSHOT 2024#VTW-360#1.0.14-SNAPSHOT Eh?
2023.VTW-360.1.0.14-SNAPSHOT 2024.VTW-360.1.0.14-SNAPSHOT Eh?
360.2023-1.0.15-SNAPSHOT 360.2023-2.0.15-SNAPSHOT Eh?
2023.360.1.0.14-SNAPSHOT 2023.360.1.0.15-SNAPSHOT Meh
1.0.19-VTW360-2023.SNAPSHOT hangs Eh?
1.0.19-VTW360-2023-SNAPSHOT 1.0.19-VTW361-2023-SNAPSHOT Eh?
1.0.19-2023-VTW360-SNAPSHOT 1.0.19-2024-VTW360-SNAPSHOT Eh?
1.0.19-YY24-VTW360-SNAPSHOT 1.0.19-YY25-VTW360-SNAPSHOT F
1-0-19-2025-VTW360-SNAPSHOT 1-1-19-2025-VTW360-SNAPSHOT Eh?
360.2023.1.0.16-SNAPSHOT 360.2023.1.0.17-SNAPSHOT MKay

Proposal 3

So we are forced to allocate meaning to digits and place, never a good idea, but it is that or try and change the behaviour of the Release Plugin, a task I do not think I have the time or the energy for.

\dcode for project
\d\d\dcode for repository
\d\d\d\dyear
\d+Major
\d+Minor
\d+Patch

I added the new proposal to the tests, and wrote some more tests based upon the above regex.

We land with 2.130.2024.2.0.6.

However much you think about the problem previous engineers will have constrained your choices.

Sunday 14 January 2024

Maven version schema change

code version schema change - hotpot.ai

I proposed a new versioning scheme to yield a unique version string for each artifact in our highly modularised Maven java application.

Currently we are running a classic SemVer semantic verioning system. The only shortcoming I can see with SemVer is that it is not globally unique. In the Maven world the version is combined with the artifactId and the groupId to create a globally unique token, but because this is within an XML based Project Object Model (POM) file it is fairly difficult to get that token out without buying into the whole toolchain. As Maven allows ranges (don't use ranges) and inheritance it is practically impossible for mortals to parse a pom correctly.

What problem are we trying to solve?

We want to be able to edit all poms across our collection with a single command to ensure that each version is completely deployed and we have no version clash. We have developed a tool to make the Maven Dependency Tree readable which has allowed us to see how often the team make a change but do not fully roll it out.

The problem we are trying to solve is how to update all usages of an artifact every time it is updated, ensuring we never run with a mixture of versions (almost like a Monolith).

In the wider open source community it is not the responsibility of the library writer to ensure that every usage is updated to the latest version but within an enterprise it is.

Initial proposal

My first proposal, prepending the semantic version number with a unique code for the library, looked good:

SMD110-3.0.8

This system would work if we had started with this or if we were to backfill all previous versions, however we are proposing a change only to new versions and we have to ensure that the new versioing system will play nicely with the existing versions.

By play nicely I mean that SMD110-3.0.8 should be understood to be more recent than 3.0.7.

I had planned to test this by trial and error but then I thought to actually write a test.

Testing the proposal

I found the Maven verson comparison code and wrote some tests.

The tests revealed my assumption to be incorrect (whether this is a bug or not I am not sure), but the tests enabled me to propose a schema change which did play nicely:

    @Test
    public void workableNextYearNewOldComparisonTest() {
        ComparableVersion it = new ComparableVersion("2025-SMD130-2.0.7");
        ComparableVersion previous = new ComparableVersion("2024-SMD130-2.0.6");
        assertTrue(it.compareTo(previous) > 0);
        assertTrue(previous.compareTo(previous) == 0);
        assertTrue(previous.compareTo(it) < 0);
    }

Revised proposal

Prepending the initial proposal with the year is an improvement, the year of publication is useful and it works with the tooling:

<year>-<artefact code>-<semantic version>

2024-SMD110-3.0.8

Test your assumptions, it is easier than trial and error!