Is Moodle using semantic versioning?

Is Moodle using semantic versioning?

by Juho Jaakkola -
Number of replies: 19

Is Moodle using semantic versioning (http://semver.org/)? It looks like it is, but when you look closer it seems this isn't the case.

I read this but I'm really not sure: https://docs.moodle.org/dev/Moodle_versions

Semantic versioning has three parts:

  • MAJOR version when you make incompatible API changes
  • MINOR version when you add functionality in a backwards-compatible manner
  • PATCH version when you make backwards-compatible bug fixes
It seems to me that Moodle uses only two of these despite having a three-part version number. It seems to me that in practice the first two numbers are the same thing.

Can someone shed some light to this and correct me if I'm wrong?


Average of ratings: -
In reply to Juho Jaakkola

Re: Is Moodle using semantic versioning?

by Conn Warwicker -
Picture of Core developers Picture of Plugin developers

Yes, the first 2 are the major version.

E.g. 2.4, 2.5, 2.6, 2.7, etc... are all major versions, as opposed to "2" being the major version

the 3rd part is the minor version of that major version

In reply to Juho Jaakkola

Re: Is Moodle using semantic versioning?

by Tim Hunt -
Picture of Core developers Picture of Documentation writers Picture of Particularly helpful Moodlers Picture of Peer reviewers Picture of Plugin developers

Not really.

After 2.9 will come 3.0, but that is not any different from the change from 2.8 to 2,9.

In Moodle terms 2.x -> 2.y (or 2.9 to 3.0) is a major version, and may have API changes (which are normally documented in the release notes.)

2.9.z is a minor version. We don't number patches, but every week there is a 2.9.z+ weekly release. All patches are, of course, available from the git repo.

Average of ratings: Useful (3)
In reply to Juho Jaakkola

Re: Is Moodle using semantic versioning?

by Juho Jaakkola -

Ok, thanks for clarifying it!

I must say that I in my opinion Moodle should also adopt Semver for versioning.

I would like to know that if I make a plugin for 3.0.0 it will still work without changes during the whole lifetime of version 3.x.x no matter how many minor releases (e.g. 3.12.x) were made.

As a plugin developer, I find the current way misleading.
In reply to Juho Jaakkola

Re: Is Moodle using semantic versioning?

by David Mudrák -
Picture of Core developers Picture of Documentation writers Picture of Moodle HQ Picture of Particularly helpful Moodlers Picture of Peer reviewers Picture of Plugin developers Picture of Plugins guardians Picture of Testers Picture of Translators

I personally like Tom Preston-Werner's semantic versioning, too. Especially for the node.js packages and similar repositories. But I am not sure about actual benefits being worth of a change for the Moodle core.

The main motivation for the semantic versioning, as I understood it, was to make the format unified and standardized so that package dependency managers (such as npm in node.js) can rely on it. That is not our case in 99%, I believe.

Moodle's development model has become date-driven years ago and it seems to work very well since then (definitely better than feature-driven model used before). If there was a need for a change in the versioning scheme (and again, I don't think there is), it would be more natural to follow Mahara and switch to the Ubuntu-like date based version numbers, such as Moodle 15.05 (for the version released in May 2015).

if I make a plugin for 3.0.0 it will still work without changes during the whole lifetime of version 3.x.x

No. If you submit a plugin to the Plugins directory, you will declare it supports Moodle 3.0. Moodle does not make any API and significant UI changes on stable branches so your plugin should work without changes for all 3.0.0, 3.0.1, 3.0.2, ... 3.0.x Moodle versions. Moodle 3.1.0 will be next major release (with API and UI changes expected) and you as the maintainer are supposed to check it works well there.

You can still think in terms of semantic versioning in Moodle, as Tim exaplains. Given Moodle version X.Y.Z, you just need to consider X.Y as the major version and Z as the minor version.

In reply to David Mudrák

Re: Is Moodle using semantic versioning?

by Juho Jaakkola -
Moodle's development model has become date-driven years ago and it seems to work very well

Using Semver does not prevent you from continuing the date-driven releases. You can for example make:

  • Major version once a year
  • Minor version once a month
  • Patch version every week

it would be more natural to follow [...] Ubuntu-like date based version numbers, such as Moodle 15.05 (for the version released in May 2015).
Semver doesn't prevent this either! Let's continue with examples using the release schedule I mentioned above. Using the date-driven approach the major (non-BC) versions from different years would then take the form of:

  • 15.5.1 (Released in 2015 on May 1st)
  • 16.3.8 (Released in 2016 on March 8th)

For the version from 2015 the minor versions (BC-compatible API changes) could be for example:

  • 15.1.1 (Released 1st of January)
  • 15.2.1 (Released 1st of February)
  • 15.3.1 (Released 1st of March)
  • etc.

And respectively the patch releases (bug and security fixes) could be:

  • 15.5.1 (Released 1st of May)
  • 15.5.8 (Released 8th of May)
  • 15.5.15 (Released 15th of May)
  • etc.


You can still think in terms of semantic versioning in Moodle, as Tim exaplains.

This is not true. "There will be changes to API or UI" is not enough information for a plugin developer.

There's a clear difference between changes that :

  1. Have been made in a BC-way
  2. Have not been made in a BC-way

This is the idea behind Semver; It is able to communicate to the developer whether the API/UI changes have been made in a backwards compatible way or not.

Moodle's current versioning fails to do this. And this causes extra work for plugin devs, as we currently need to manually check whether our plugins work in each X.Y release.

In reply to Juho Jaakkola

Re: Is Moodle using semantic versioning?

by David Mudrák -
Picture of Core developers Picture of Documentation writers Picture of Moodle HQ Picture of Particularly helpful Moodlers Picture of Peer reviewers Picture of Plugin developers Picture of Plugins guardians Picture of Testers Picture of Translators

is not enough information for a plugin developer

I don't think the version number itself can provide such information - be it semver or not. When we increase the major version number in Moodle (such as from 3.0 to 3.1), we simply reserve right to make non-bc changes (in the API, database structure or UI). On contrary, all changes should be considered as backwards-compatible on minor releases (such as from 2.9.1 to 2.9.2).

I can't really see "clear difference" between what Moodle does and what semver does, unless I am missing something,

In reply to David Mudrák

Re: Is Moodle using semantic versioning?

by Juho Jaakkola -
all changes should be considered as backwards-compatible on minor releases (such as from 2.9.1 to 2.9.2).

Yes, but isn't this just because the changes do not contain new features in the first place? At least according to the docs they don't:

Minor versions are released every two months, including both bugs and security issues fixed.

So currently Moodle releases are either:

  1. Bug/security fixes
  2. New features (that can be BC or non-BC)
What Semver does is that it uses three levels instead of just two:

  1. Bug/security fixes (version n.n.X)
  2. New features that are BC (version n.X.n)
  3. New features that aren't BC (version X.n.n)
If Moodle started using the three-level system, it would allow Moodle sites to get all the latest and greatest features (note: not just bug and security issues) from the newest n.X.n version without having to worry whether some of the installed plugins would get broken because of the upgrade.

So that's what the goal would be; The ability to get new features without having to worry at all about backwards compatibility.


This naturally does not get fixed just by changing the way how version number is incremented. (Maybe I was unclear about this earlier). Instead it would require Moodle to have separate git branches for each version (major, minor, patch).

When producing new code, developer would choose the correct branch depending on whether the change is a fix, new BC feature or a new non-BC feature.

I hope I'm making sense. smile

In reply to Juho Jaakkola

Re: Is Moodle using semantic versioning?

by Eric Merrill -
Picture of Core developers Picture of Moodle HQ Picture of Peer reviewers Picture of Plugin developers Picture of Testers

The problem is that it makes a branch hell for devs, and makes documentation harder. You now have 3 levels of branches that have to be maintained:

X-1.Y.z
X-1.Y-1.z
X-1.Y-2.z

X.Y
X.Y-1.z
X.Y-2.z

X+1.Y

Plus, in the Moodle community particularly, this is probably of limited value. Most larger Moodle installs don't want mid-stream new features. Not only do they still have to test everything, but they have to update documentation, and training, etc. The marginal cost to test all their plugins to make sure they are still working in minimum when they only plan on updating once or twice a year anyways.

The other thing this does is it makes it harder to jump to the X+1 release. Right now we move in small, steady jumps. Very few things break between each release, so the work is minimal. What would almost certainly happen is that people would never leave the X release to the X+1 because it will just be too much work. We saw that with 1.9, and you see it in other projects. The current system does a better job at keeping sites more current.

The thing is, current Moodle numbering system already tells you that, when Y changes, they can't garantee that your plugins will continue to work, you have to test them, because there are almost always API changes in those releases. The only thing that really added confusion to the mix was the choice to go to 3.0 instead of 2.10. Because there are no plans for a major rework in the pipeline, it was decided that it was less cumbersome to let it roll forward to 3.0, and I agree. There is another way to look at it - The next major version is so different from 2.0, that it deserves it be a new major release, even though we have gotten there via evolution.

While I get the benefits of semantic versioning, as both a plugin dev and a large site admin, I think it would just add workload and confusion with very little upside.

Average of ratings: Useful (6)
In reply to Eric Merrill

Re: Is Moodle using semantic versioning?

by Tim Hunt -
Picture of Core developers Picture of Documentation writers Picture of Particularly helpful Moodlers Picture of Peer reviewers Picture of Plugin developers

This article was a good summary of why Semantic versioning sounds good in theory, in practice it does not work https://gist.github.com/jashkenas/cbd2b088e20279ae2c8e

In reply to Tim Hunt

Re: Is Moodle using semantic versioning?

by Juho Jaakkola -

I really would not recommend using that article to form an opinion about Semver. The author hasn't fully understood how it works.

I apologize for being harsh, but it's basically saying:

"Semver doesn't work because it is bad and it's bad because it doesn't work. And it's impossible for you to use it correctly because someone else in some other project doesn't know how to use it correctly."

There really aren't any rationalized arguments in it.


But in any case, it seems there isn't interest to reconsider Moodle versioning at the moment. So I'll stop bugging you for now. smile

Thanks to everyone who listened to my rants and shared their opinions.

In reply to Eric Merrill

Re: Is Moodle using semantic versioning?

by Visvanath Ratnaweera -
Picture of Particularly helpful Moodlers Picture of Translators
Hi

Thanks for bringing the article http://semver.org/. Lot of thoughts have gone in to it.

My question: How does the LTS fit in to this? See "Next Moodle LTS?" https://moodle.org/mod/forum/discuss.php?d=315301.
In reply to Visvanath Ratnaweera

Re: Is Moodle using semantic versioning?

by Juho Jaakkola -

Semver doesn't affect LTS necessarily at all. It is possible for the Moodle core team to make as many patch releases as they want.

Even the numbering wouldn't change for this. The third version number  (x.y.Z) would be incremented as usual on each release.

In reply to Juho Jaakkola

Re: Is Moodle using semantic versioning?

by Michael Aherne -
Picture of Core developers Picture of Peer reviewers Picture of Plugin developers

I like the idea of Moodle using semantic versioning too, but also think it's really difficult to view the whole of Moodle as a single API! What might be an interesting idea would be to use semver for the APIs that comprise Moodle individually.

To give an example, I run a pretty large Moodle installation which currently has 80 non-core plugins. When we upgrade to a new version of Moodle each year, I spend pretty much an entire working month puzzling over upgrade.txt files, grepping for uses of functions that have changed or been deprecated, updating the code to the new API etc. It would be fantastic to be able to declare what API versions a plugin was written against and have Moodle indicate which had changed to a non-backwards-compatible version, and which might have new backwards-compatible functionality I might want to consider using. For example:

$plugin->dependencies = array (
'core_block' => '2.3.5', // Block API
'core_cache' => '1.1.2', // Cache API
'core_dml' => '1.0.0', // DML API
'core_file' => '1.0.1', // File API
'local_strathuserselect' => 2015052000,
'local_strathcourseselect' => 2015052000
);

I realise this might be a fair amount of work to implement and keep up-to-date, so may not practically be worth doing, but it would be a useful feature for plugin developers. It certainly seems a more workable way of using semantic versioning in Moodle than trying to use it for the product as a whole.

Average of ratings: Useful (1)
In reply to Michael Aherne

Re: Is Moodle using semantic versioning?

by Derek Chirnside -

Off topic.

80 non core plug-ins, Michael.  This is a lot. Have you thought if these are worth it to submit to core??

Are they in the plug in database? If not, could putting them there help you with testing?

-Derek


In reply to Derek Chirnside

Re: Is Moodle using semantic versioning?

by Michael Aherne -
Picture of Core developers Picture of Peer reviewers Picture of Plugin developers

That's a good question, Derek. I did a quick calculation and they work out as:

  • 17 legacy plugins that we're in the process of getting rid of
  • 14 third party plugins
  • 43 integration / plumbing type of things that are very specific to Strathclyde. Many of the university systems are in-house developments, and there are also a couple related to specific university policies.
  • 3 we have released, although only 1 is currently in the plugin directory (atto_morebackcolors, local_nagios, mod_strathpa)
  • 3 we could potentially release: "my coursework", which shows a list of all of a student's forthcoming deadlines; "my groups", a really dumb block that just shows which groups a student is a member of; "profile enrolment", an enrolment plugin that enables enrolment in a course based on user profile field values.

It's the usual problem with these things - the plugins were developed to deal with specific issues in the university rather than as useful generic Moodle functionality so, while they could be fairly easily turned into sane versions that could be released, it's hard to justify putting time into that when we have so much other work to do! If I can find some spare time I'll have a look at it, though. In particular, the enrolment plugin would be easy to get into a state that could be released, and would probably be a generally useful one.

In reply to Michael Aherne

Re: Is Moodle using semantic versioning?

by Just H -

I think if you released the "profile enrolment"plugin you'd make a lot of people happy smile

Average of ratings: Useful (1)
In reply to Just H

Re: Is Moodle using semantic versioning?

by Michael Aherne -
Picture of Core developers Picture of Peer reviewers Picture of Plugin developers

Thanks, guys! I'll have a look at getting it released. After posting that it would be "easy" to release it, I realised it has a dependency on another non-generic plugin that I probably can't release, which will complicate matters. Hopefully it won't add too much work and I'll be able to get it sorted out. It is quite a useful plugin, so it would make sense to open source it properly.

In reply to Michael Aherne

Re: Is Moodle using semantic versioning?

by Juho Jaakkola -

Just some food for thought:

If it is difficult to see Moodle as a single API, one approach for managing all those APIs would be to actually make them different projects. This is for example how the Symfony framework is doing it: http://symfony.com/blog/symfony2-components-as-standalone-packages

Each API would then have their own version number, and each third-party plugin could define the exact APIs and API versions it requires.

The API projects would naturally need to be included in the main project. One way to do this could be to use composer (https://getcomposer.org/doc/00-intro.md). A simple "composer update" command would fetch and install all the correct API versions automatically.