I've recently (finally!) started using Git to track a few custom themes we use/develop. That has also inspired me to be more deliberate with the version and release numbers in the respective version.php files, and also the Git tags we apply to released commits. I've read the Moodle Dev docs and observed the conventions in some plugins from the Moodle.org repository to get some ideas.
I am wondering how to handle a particular case: what if a new version of Moodle comes out, and we confirm that the theme is compatible with the new version without needing any changes? I would like some part of the version.php file or version control to indicate that it is compatible with the new version of Moodle, but that it is not any different from the previous version, and therefore it is not necessary to actually update the plugin.
My instinct would be to update the release value to reflect this ("3.x for Moodle 3.y+" or something). However, since the plugin has not really changed, it feels like making a new Git tag or version number would misrepresent the status of the code.
Before I make up some solution, I figured I would ask, since I am sure others have encountered this issue (although I could not find anything after scouring the forums). Particularly, if we try to employ some kind of automated solution for upgrades, it would really help for our plugins to use a scheme that is similar to other Moodle plugins. I'd appreciate any insight!
Guidelines for plugin version numbers, especially when new versions of Moodle come out
by Ray Hinton -
Number of replies: 10
In reply to Ray Hinton
Re: Guidelines for plugin version numbers, especially when new versions of Moodle come out
by Michael Milette -
Hi Ray,
If your plugin published on Moodle.org is compatible with a newer version if Moodle without any changes, just edit your submission and add the new version of Moodle to it without uploading a new version. Some of my plugins have not required any changes since several versions of Moodle and this is what I do.
The problem with indicating exact version compatibility in version.php is that not every maintainer will keep their plugins up to date yet there is a good chance that it will work just fine in subsequent releases of Moodle.
Another option I have seen some maintainers use is to create a new branch of their plugin for each release of Moodle. Personally I would only do this if there was such a big change to my code that I did not want to have to maintain backwards compatibility.
If you really want to update your plugin to reflect compatibility with a newer version of Moodle without making changes to your code, update the documentation or the copyright notice and then submit that as a new release without changing the version number so that it doesn't unnecessarily trigger plugin updates for everyone currently using it.
Best regards,
Michael
If your plugin published on Moodle.org is compatible with a newer version if Moodle without any changes, just edit your submission and add the new version of Moodle to it without uploading a new version. Some of my plugins have not required any changes since several versions of Moodle and this is what I do.
The problem with indicating exact version compatibility in version.php is that not every maintainer will keep their plugins up to date yet there is a good chance that it will work just fine in subsequent releases of Moodle.
Another option I have seen some maintainers use is to create a new branch of their plugin for each release of Moodle. Personally I would only do this if there was such a big change to my code that I did not want to have to maintain backwards compatibility.
If you really want to update your plugin to reflect compatibility with a newer version of Moodle without making changes to your code, update the documentation or the copyright notice and then submit that as a new release without changing the version number so that it doesn't unnecessarily trigger plugin updates for everyone currently using it.
Best regards,
Michael
In reply to Michael Milette
Re: Guidelines for plugin version numbers, especially when new versions of Moodle come out
by Ray Hinton -
Hi Michael,
Thanks for the detailed feedback. I think that what I am ultimately learning is that, since there is no strictly-enforced convention, it is more important to just choose something and be consistent with it. The actual version number in version.php seems to be the most important, since it can trigger an update in Moodle.
In your final example, if I am updating the README or LICENSE files that I have in my plugin, that would look like a change to the codebase (a new commit since the last tagged release). Would you also tag that commit to indicate something about the new Moodle version? Perhaps remove the tag from the last release and apply it to the new commit? Of course, actually looking at the commit message and/or code changes would make it immediately obvious that nothing substantial was changed, so maybe the answer in this case is to not tag anything, and diligently review changes before applying them (as always).
Frankly, this is the first time I am using Git in any meaningful way, so I am sure that I have some misconception or I am overthinking something. Anyway, thanks again for your insight!
- Ray
Thanks for the detailed feedback. I think that what I am ultimately learning is that, since there is no strictly-enforced convention, it is more important to just choose something and be consistent with it. The actual version number in version.php seems to be the most important, since it can trigger an update in Moodle.
In your final example, if I am updating the README or LICENSE files that I have in my plugin, that would look like a change to the codebase (a new commit since the last tagged release). Would you also tag that commit to indicate something about the new Moodle version? Perhaps remove the tag from the last release and apply it to the new commit? Of course, actually looking at the commit message and/or code changes would make it immediately obvious that nothing substantial was changed, so maybe the answer in this case is to not tag anything, and diligently review changes before applying them (as always).
Frankly, this is the first time I am using Git in any meaningful way, so I am sure that I have some misconception or I am overthinking something. Anyway, thanks again for your insight!
- Ray
In reply to Ray Hinton
Re: Guidelines for plugin version numbers, especially when new versions of Moodle come out
by Paul Holden -
Hi Ray,
Assuming you are using Travis to automate testing of your plugins, you would at the very least want to add the new Moodle version branch to your testing matrix 🙂
Once tests pass on the new version, you can tag the release and publish to the plugins repository.
In reply to Paul Holden
Re: Guidelines for plugin version numbers, especially when new versions of Moodle come out
by Brian Merritt -
Agreed - the minimum is to update the branch to track Moodle releases and compatibility and update the plugins portal.
When confirming support for a new Moodle release, it's worth updating the version.php requires Moodle version etc details as well as bumping version number.
When confirming support for a new Moodle release, it's worth updating the version.php requires Moodle version etc details as well as bumping version number.
In reply to Brian Merritt
Re: Guidelines for plugin version numbers, especially when new versions of Moodle come out
by Ray Hinton -
Thanks for the reminder about the "requires" number. In the example I was thinking about, the plugin would still be compatible with the older version of Moodle, while also being verified to work with the new version (I forgot to mention this part of the hypothetical situation 😀), so I would not update the "requires" number. If compatibility is lost (David mentions 3.8 having some significant changes), then I'd need to update "requires".
In reply to Ray Hinton
Re: Guidelines for plugin version numbers, especially when new versions of Moodle come out
by David Mudrák -
I also wanted to point to just recently added MDL-59562 - ability for plugins to declare which major stable versions of moodle are supported directly in their version.php file (supported since Moodle 3.9)
In reply to David Mudrák
Re: Guidelines for plugin version numbers, especially when new versions of Moodle come out
by Ray Hinton -
Ahh, thanks! I saw that in the dev docs page, but didn't see it in any of the plugins that I observed. If it is brand new for 3.9, that explains it. I'll probably wrap this into our workflow once we get on that version.
In reply to Paul Holden
Re: Guidelines for plugin version numbers, especially when new versions of Moodle come out
by Ray Hinton -
Hi Paul,
Automated testing/CI are a bit beyond us at the moment.
But, I think the gist of your suggestion lines up with Michael's: the codebase does not necessarily need to reflect the Moodle version compatibility, as long as we are documenting that information somewhere else in our workflow.
In our case, this is especially true, because we are not releasing anything on the Moodle.org repository at this point. If we were releasing it publicly, conforming to a couple more conventions would be helpful to others using the plugin, but for purely internal use, we can afford to be sparse. Thank you for your thoughts!
- Ray
Automated testing/CI are a bit beyond us at the moment.
In our case, this is especially true, because we are not releasing anything on the Moodle.org repository at this point. If we were releasing it publicly, conforming to a couple more conventions would be helpful to others using the plugin, but for purely internal use, we can afford to be sparse. Thank you for your thoughts!
- Ray
In reply to Ray Hinton
Re: Guidelines for plugin version numbers, especially when new versions of Moodle come out
by David Mudrák -
Good questions, thanks Ray for starting the thread.
I personally tried various versioning and release naming schemes in my plugins. I have not found a nice & working solution for having the list of supported Moodle versions reflected in the plugin's version number. What finally seems to work best for me is to have my own version sequence without a numerical dependency on the Moodle version number, and mention the relation to the Moodle version in the release notes, version.php and the plugin description.
Additionally I try to adapt the ideas and spirit of the semantic versioning. When the list of supported Moodle versions change (typically I drop support for older Moodle versions), I release a new plugin version with the higher major version number etc. That way, one major plugin version supports a range of Moodle core versions. And I do breaks only for good enough reasons (e.g. Moodle 3.8 is a good candidate due to its new options of handling the JS modules).
In reply to David Mudrák
Re: Guidelines for plugin version numbers, especially when new versions of Moodle come out
by Ray Hinton -
Thanks David! The more feedback I get, the more it is becoming clear: there is really no one-size-fits-all method, so I should just make sure I am clear and consistent with whatever I do.