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.
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.
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.
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.
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.
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.
@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.
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.
First of all: MKPs with old versioning should still work (and compare “older” to valid semver versions). If that is not the case please send us feedback via the beta channels!
As for when you edit an MKP (== create a new version of it):
Sorry, maybe I was a bit unclear. We’re enforcing the format of a semantic version number, but not the semantics of it.
The semantics clearly describe which part of a version number must be incremented depending on how the software package changes and vice versa. That is a very powerful tool in software development, but it requires a lot of discipline and might be overkill for regular MKP maintenence. We cannot (and don’t need to) enforce that.
But since you can now have more than one version of a package in your site, we need a reliable, transparent and predictable way to order the packages, so we had to introduce some sort of standard. Using the format of a semantic version number allows sorting, and there’s no reason not to go with the industry standard.
Now, a wild guess: You want to include the date, rather than <major>.<minor>.<patch> version. That is not the intended semantics, but you can do that anyway. Just make sure it fits the format, for instance 2023.04.04-v.0.9 should be ok. Note that 2023.05.05-v.0.1 will be considered newer then.
The “semver” way would be to use the build information field, I guess: 0.9.0+2023.04.04, but that is entirely up to you.
