Semantic versioning of MKPs

Hey all,

Today we made some changes on the Checkmk Exchange.
For the sake of consistency and to make the review process easier for our developers we have introduced some changes to the versioning of MKPs.

tl;dr
Moving forward we the version field of an MKP has to follow semantic versioning 2.0.0 standards.
This will only affect newly uploaded MKPs, all MKPs already present on the Exchange we remain unchanged.

Currently, there are no real restrictions on the version field. This can lead to confusion, not only for our developers who review the MKPs but also for people who are searching for MKPs on the Checkmk Exchange.

With the introduction of semantic versioning we can ensure that, moving forward, the version field of the packages on the Exchange follow the same structure.

A normal version number MUST take the form X.Y.Z where X, Y, and Z are non-negative integers, and MUST NOT contain leading zeroes. X is the major version, Y is the minor version, and Z is the patch version. Each element MUST increase numerically. For instance: 1.9.0 → 1.10.0 → 1.11.0.

You can find more about Semantic Versioning on https://semver.org/

Moving forward the upload of an MKP will fail when the version field does not follow the rules specified in the Semantic Versioning 2.0.0 guidelines.

What does that mean for you as a package creator?

If you have created a new package, and you want to upload the first version to the Checkmk Exchange. We suggest that when you create the MKP you with a version 1.0.0.

If you want to upload a new version of an existing package. This new version should now follow semantic versioning standards.
Currently, many MKPs have X.Y versioning. For example, let’s say your last version was 5.7 then we suggest you create your next MKP with the version 5.7.1 or higher.

1 Like

I appreciate that but have a question: will checkmk itself follow these guidelines? I mean, 2.1.0p18 is not a valid version number according to the new rules.

2 Likes

No this is purely about the versioning of the MKPs. I can’t predict the future, but for now Checkmk itself will not follow the semantic versioning guidelines.

1 Like

IMHO it would be good to have the first two be the same as the checkmk version the extension has been made for. I do not think that any extension needs more than the patch level number (the last of the three) to distinguish between versions.

This would it make easier to find the correct version of the extension for a given checkmk site.

1 Like

That sounds good. But it would only work if it is enforced. So, that would basically mean the first 2 numbers would be pre-filled while creating the MKP. I will discuss internally to see what the implications would be.

2 Likes

@Dirk : You are right. I personally would love to see Checkmk itself switch to semantic versioning, but I can’t see it happen anytime soon.

2 Likes

@r.sander : I disagree; for various reasons:
The most important thing of this change for us (backend maintainers, QA, developers) is that we have a unique name and an increasing version number for all packages. If I get presented with Package “Bar Extender 2.3.7”, I must be able to decide what its predecessor (on the Exchange) is. If I can have a situation where “2.0.12” is newer than “2.1.4”, that gets difficult.
Also there are packages that are compatible with more than one Checkmk version (I just saw one that claims to be compatible from 1.2.8 onwards!).
Also this would be one thing more to explain, one thing more “out of the ordinary”.
Lastly, a bit more theoretical, but important nevertheless I think: This would undermine the concept of semantic versioning. As the name suggests, it is not only a format spec for versions, but also gives a particular meaning to the elements of such a version (major, minor and patch version, prerelease version and build metadata). It is not only about having an order of the different versions, but also describing in what way the package changed.

I realize that one might have to maintain two “flavours” (I’m avoiding the word ‘version’ here…) of the same package, one for Checkmk 2.0 and one for 2.1. I’d suggest including this in the package name, as was done for python packages while python2 and python3 where maintained.

I know this might sound a bit pedantic, but I really believe that a major strength of this approach is following “Semantic Versioning 2.0.0” by the book.

2 Likes

You are correct. Sometimes development is not straight forward.

1 Like

And this is where I think makes it a tad bit overly bureaucratic for most extensions. They are so simple that development is just straight forward, e.g. they never add new festures.

Please remember that the audience of checkmk are system administrators and not software developers. Therefor community extensions are made by system administrators. I do not know if you encourage participation with such a step. People now have to think about their “development process” and if they even have one.

What is with situations where we have to backport a change to a package that has to be compatible with 2.0 or even 1.6?
There are a number of small incompatabilities between 2.1 and 2.0 that have to be tracked.

(I’m not entirely convinced I understand you correctly, but this is my answer:)
That is why you’ll have to include the Checkmk version in the name of the package. Once you’ve uploaded “Bar Extender 2.1.3” you cannot upload older versions anymore - the lowest uploadable version will be “2.1.4”.
You can have “Bar Extender (Checkmk 2.0) 1.0.3” and “Bar Extender (Checkmk 1.6) 1.0.4”. But it would be wrong to claim that one is a later version of the other one; they are packages in their own right, and can be upgraded independently from one another.

We are not enforcing the semantics of the versioning. If you used to versionise using “1”, “2”, “3”, all you have to do is use “1.0.1”, “1.0.2”, “1.0.3” now.

The problem here is (one that we often face in Checkmk): We have to have a way that is not too complicated in simple cases and allows for cases where things are a bit more convoluted.
You are right: Most MKPs don’t add new features during their lifetime. I see it this way: If you wanted to, you could now convey this information by the version number. If you choose not to: No harm done.

You can have “Bar Extender (Checkmk 2.0) 1.0.3” and “Bar Extender (Checkmk 1.6) 1.0.4”. But it would be wrong to claim that one is a later version of the other one; they are packages in their own right, and can be upgraded independently from one another.

Hm, maybe I’m misunderstanding something, but then a user has to select the right package and when you link to an extension you have to possibly provide 3 links for each version of the “bar extender (check_mk X.Y)” package - or do I have a chance to link between packages within exchange.checkmk.com?

Yes, but in either case you have to select the right package…

Fair point. Currently you can not do that. I still believe that this problem should not be solved by encoding some meta information into the MKP version number, but I agree that it would be nice to somehow “bundle” those packages. Maybe @baris.leenders has an idea?

The weird thing is that currently MKPs are built from a deployed copy of themselves, which prevents us from implementing other interesting options such as having files for different Checkmk versions in one single MKP.