Contributed plugins versioning
Moodle core itself has a solid versioning scheme (see the documentation page describing it). However, authors of contributed plugins are pretty free to use their own system of versions numbering. As the author of some contributed plugins, I was looking for a good versioning scheme for my contributions. From my point of view, such a “good” solution should (1) be stable in the long-term period and (2) intuitively describe the required Moodle core version the version of the plugin is for.
After considering several alternatives, I ended with a system similar to the one used by the Moodle core itself. So I use versions consisting of three numbers separated by dots, for example “2.1.3″. The first two of these numbers declare the Moodle branch the plugin is intended for. So the plugin with the version 2.1.3 would be for Moodle 2.1.x. The last number is the sequential update number. And of course, the plugin with the version 2.1.3 would be the fourth update of the plugin as all real geeks who were breast-fed by C like languages start counting with zero (2.1.0 was the initial release of the plugin).
This scheme fits well the convention of using standard Moodle names for development branches in Git. The repositories of my contrib plugins have branches MOODLE_21_STABLE etc like the Moodle core has. So the plugin version 2.1.3 would be born on MOODLE_21_STABLE branch in its repository. Naturally, I use Git tags for the version releases points. Luckily there was no need to re-invent anything here as together with the switch from CVS to Git, Moodle started using standard tags like v2.1.3 instead of legacy MOODLE_213 style.
Just today, I realized this approach has yet another aspect I did not fully realize initially. It forces the plugin maintainer to release new plugin version together with the Moodle major release. Even if there is no real update of the plugin. As an example, the Course contents block is pretty feature complete and there are no known bugs in it (ok, that’s a bit of blaspheming). The most recent version of it was 2.1.2. Now when Moodle 2.2 is released, I had to go and release 2.2.0 of the block to follow my guidelines. Even when the code of the block has not changed.
Is it a disadvantage of this scheme? I believe it’s not. It’s actually a great opportunity to confirm that the plugin still works on the most recent Moodle version. And also it’s the information for the users that the plugin is still actively maintained. Even by releasing the new version for purely formal reasons, I as the maintainer declare publicly that I tested the current version of the block with Moodle 2.2 and consider it stable and working. And that is worth going through the whole release procedure – branching, tagging and uploading the new version to the plugins directory.
January 7th, 2012 at 05:06
This looks good if:
1) You only release new features every 6 months, in line with the new Moodle releases.
2) When you release a new feature, you don’t want to make it available for older versions of Moodle, even if it would run on them perfectly well.
If those things don’t hold, something odd is going to happen. The fundamental problem is that since you’ve given up the major version version slots to the Moodle numbering, you’re only left with a point release to show what features you’ve got.
For example:
I’ve made my first release for Moodle 2.0.
mymodule 2.0.0
Bug fix:
mymodle 2.0.1
I make a new feature for my module. What do I call it? Calling it:
mymodule 2.0.2
…would violate the Principle of Least Astonishment, because the normal convention is that a new feature produces a new minor version number, and risk an admin upgrading expecting security and bug fixes, and ending up confusing users with functionality changes.
But I can’t do:
mymodule 2.1.0
…because Moodle 2.1 isn’t out yet.
So I’m going to have to wait to release my software because I don’t have a way to number it, which is a bit mad. But say I do. I wait 6 months and Moodle 2.1 comes out.
mymodule 2.1.0.
Huzzah. I can release the functionality somebody contributed 5 months ago.
But people who only want to upgrade my module without upgrading their whole Moodle are going to be SOL. And there are probably quite a few people like that, because they’re waiting for some other module they rely on to get upgraded too.
I suppose I could ignore the normal convention and put new functionality into the point release.
2.0.2
Then Moodle 2.1 comes out and I do:
2.1.0
But 2.0.2 and 2.1.0 are the same thing. WTF? And it gets worse every 6 months – in 3 years I’ll have 6 different version numbers, all pointing at the same thing.
I think the right thing to do here is to look at a system that’s managed to make a really modular system work properly and copy them. The obvious one is Drupal, who do things like this:
6.x-3.10
6 tells you that it works on major version 6 of Drupal.
x tells you that it works on any minor version of Drupal. If it only worked on Drupal 6.2, it would be called 6.2-3.10.
3 is the major version of the module, which tells you about functionality changes.
10 is the point release of the module, which is separate from the major version so you can be confident that you can upgrade to get bug fixes and security patches without shocking your users.
January 8th, 2012 at 20:27
Thanks Edmund for your comment. Yes, I can see your point. However, I personally gave up on this level of granularity for my contributed plugins. While it is crucial to distinguish major/minor changes for things like some software’s core libraries as there are dependencies on the provided API etc, my plugins are the leaves of the dependency tree. There are no other plugins relying on them. Even trying to maintain a “stable” and “development” branches for these small components used to look too much as an overkill to me. So I simply gave up and have a single sequence of the software updates. That is, the example version in the blog “2.1.3″ can be read as “2.1-3″ in the Drupal speech. Given that I reserve the right to append new features on older branches, sure.
I agree that is suboptimal and other contributors might prefer more robust solutions. Thanks for your example provided.
January 12th, 2012 at 20:40
David -
We are struggling with exactly the same issue, and pretty much concluded the exact same strategy.
The downside is having to maintain multiple branches of exactly the same code, where only the version.php file is different.
So, for example, the questionnaire plugin has MOODLE_20_STABLE, MOODLE_21_STABLE and MOODLE_22_STABLE, but there is no difference in functional code. In the Plugins database on moodle.org, I have to either add three downloads, or one for the three versions. If I go with one, then the “requires” part of the version file needs to be the oldest version of Moodle it supports.
But, I think we have concludes, as you have, that the extra maintenance of three identical versions is still worth it to avoid confusion.
mike