releasing modules using semantic versioning

Dear all!

as stated here

OpenMRS uses semantic versioning


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.

but I often encounter modules which do not include all 3 parts of the proposed major.minor.maintenance style.

@dkayiwa you released the 1.0 of

is there a reason why the patch version is not added if its the first release?

Seems to go against semantic versioning.

@teleivo, we have not religiously followed this for modules. :smile:

I don’t know if this was ever explicitly considered by anyway, but in practice, most modules rarely have maintenance versions at all.

So actually doing semantic versioning hasn’t been a real issue because everything is implied to have a maintenance version of .0.

Many smaller modules get their bugs fixed in minor versions. This is, in part, because maintenance versioning works best when you maintain minor version branches (like 1.2.x), which is more trouble than it’s worth for many modules. Assuming “.0” when the maintenance version is missing is okay. When/if a maintenance version is needed, the third spot is still there for you.

It’s the modules that have adopted version numbering like that I’d like to see evolve to the major.minor.maintenance pattern.

We should religiously follow the actually guidelines we set.

Seems like we agree that also modules should follow semver. I think the maintenance portion should also be included even if its 0 since that’s what semver says.


FYI, I’ve started releasing modules using semantic versioning, see coreapps and owa. More modules can be released that way with the imminent Reference Application 2.5 release.

1 Like

but for example latest rest release (2.16) omits the maintenance portion

Yeah, sorry about that. Just noticed. It’s an overlook on my side.

I just released the IDGen module and switched to proper semantic version, ie including the maintenance version.

So the latest released version of IDGen is now 4.4.0.

However, the question next was what should the next snapshot version be: 4.4.1-SNAPSHOT or 4.5.0-SNAPSHOT.

I went with 4.4.1-SNAPSHOT, though for smaller modules like this I suspect the next release will actually 4.5.0.

Thoughts on the approach to take here?


I think you cant really answer this question now. I mean if there is a bug that gets reported after this release you will fix it and probably release the fix right away in 4.4.1.

But if there is no bug and you add a small new feature (backwards compatible) you will probably just go for 4.5.0

I think it shouldnt be set in stone that for small modules we always bump up the minor version in between releases.

I agree with tentatively bumping the minor version when setting the next snapshot version (ie, the 4.5.0-SNAPSHOT option). This is what we do on the OpenHMIS modules as we don’t usually know if the next release will be a big or small one. We decide what the actual version number will be just before releasing, only increasing the minor version if there is some non-breaking new functionality.

However, this does seem like an internal team development practice that shouldn’t have too much of an impact on others given that outside projects should not depend on SNAPSHOT versions of dependencies they don’t maintain.

Right, more a development/style question than anything else… Actually, I went with the 4.4.1-SNAPSHOT for the following reason:

In our build pipeline we are using the “versions” plugin to automatically increase our version numbers. For many modules in our pipeline, we only use released versions, but in some cases we rely on snapshots. If we were running on 4.5.0-SNAPSHOT and then did a 4.4.1 release, assumedly the “versions” plugin would not consider this a “later” release.


I’d also assume that first we need to update the bamboo plans for modules to follow semantic versioning when setting the next snapshot version.

(Bringing a comment from another thread back here.)

Executive Summary

When you release a module, the next version should be a minor version increment, both in Maven and JIRA.


The default assumption should be that the next release will be a minor release, not a maintenance release. If someone wants to do a bugfix-only release, they can create an extra fixVersion at the time. Thinking historically, we have almost never done maintenance releases of modules.

E.g. when you’re releasing REST 2.18.0, the next version should be 2.19.0, so (1) you’d only create a JIRA version for 2.19.0, and (2) you’d set the working version to 2.19.0-SNAPSHOT in maven.

The maven release plugin does not do this by default (e.g. when you release 2.18.0 it defaults to 2.18.1-SNAPSHOT), but maybe we can get around it with this flag (I haven’t checked how), or in our bamboo release plans.

The projectVersionPolicyId appears to not yet be released: I’m not even sure when 3.0.0 is going to happen, and the implementation of that is a little bit tricky too.

So what I did instead was It enforces semver to releases. Also, if you don’t override the development version variable, and the release ends with “.0”, it will apply the rule above.

Is that OK to enforce semver to every release using that script? Without that, the script will need to be a little smarter.

I vote +1 on enforcing semver for all modules released via bamboo.

Before I had to include the “-SNAPSHOT” in the development version variable. I guess with this script that won’t happen anymore? Is there a way to document this with a comment that’s visible on the screen where you override plan variables?

A while ago I changed the script to always add a ‘-SNAPSHOT’ on the development version (Try to enforce -snapshot on dev versions · openmrs/openmrs-contrib-bamboo@9542061 · GitHub). So, it won’t cause the same mistake again :slight_smile:

Hum, no, sorry, I cannot really modify that screen when overriding plan variables. We have the plan description below the plan name, but that’s about it.

I can always print things on the logs, but reality is that it’s a little bit too late and also it not so visible.

This change is now merged. I updated to reflect that change.

@cintiadr, I just released the reportingrest module (bamboo logs). I only specified the release version of 1.8.0. It automatically set the dev version to 1.8.1-SNAPSHOT, but I was expecting you had made it go to 1.9.0-SNAPSHOT. Is that right?