Principles and approaches for building our Moodle plugins

Our general goals

• We do not build the plugin just for ourself, we build it for the community: We make it as general, reusable and configurable as possible and avoid hardcoded behaviours and assumptions by any means.

• We keep the plugin focused and strong: We add as many features as we like and need, but we evaluate first if the requested feature could also be realized by another existing plugin, by improving a Moodle core functionality or by creating a new focused plugin.

• We keep the plugin understandable: We do not assume that our users will directly understand what we had in mind when composing the plugin. We add clear labels and descriptions, add help icons and provide helpful documentation in the README.md file.

• We do good things and talk about them: We publish the plugin on moodle.org/plugins and have our plugin assessed and finally promoted by moodle.org.

Coding principles

• Coding style

  • The Moodle coding style is mandatory.
  • The code-to-comment ratio should be well balanced. Ideally, a non-code should be able to read through the code comments and understand the basic functionality as well.

• Automated tests

  • Each feature of the plugin should be covered by a Behat test to make the plugin upgrade work easier.
  • It is not bad to have PHPUnit tests as well, but they are not part of our workflow yet.

• Continuous integration

  • All plugin changes are tested with Github Actions and Moodle-Plugin-CI.
  • Besides other things, Github Actions especially runs the Moodle Code Checker and the Moodle PHPDoc Checker.
  • Github Actions should be 'all green' all the time. Problems which are detected by Github Actions have to be fixed instantly.

• Theme support

  • Our plugins are built and tested on theme_boost with the intention that they work in standard Moodle installations.
  • Additionally, our plugins are noticeably tested on our Boost child theme theme_boost_campus.

• Translations

  • The plugins are shipping with the english language pack and nothing else.
  • All translations are done on AMOS.
  • The german translation is done and maintained by us, the plugin maintainers.
  • All other translations are done by the Moodle community.

• Plugin progress

  • The commit history should reflect the function changes and maintenance tasks, but not the individual development steps.
  • There should not be several commits for a single issue, the commit history does not need to reflect the implementation history of a particular contribution. Working branches and pull requests are ideally squashed when they are integrated into the master branch.
  • On the other hand, there should not be several functional changes mixed in one commit.
  • Each commit / functionality change should have a corresponding entry in CHANGES.md.

• Moodle release support

  • The master branch holds the continuous development stream of the plugin.
  • There are release branches for each Moodle major version, for example MOODLE_311_STABLE.
  • The latest release branch is always identical with the master branch. Older release branches will divert from the master branch as version numbers in some files will differ and as commits are just cherry-picked when being backported.
  • Generally, the current LTS version and the latest Moodle major release is supported in their corresponding branches.
  • Bugfixes are backported to all supported branches, features are not necessarily backported.
  • Releases which are published to the Moodle plugins repository are tagged with Git tags.
  • It's nice to get the early bird badge on moodle.org/plugins, but there is no need to have the release ready within this timeframe.

• Feature planning

  • All changes to the plugin are ideally reported, handled and discussed within a Github issue first.
  • The same applies for plugin ideas which are just put to the backlog. These should be managed in Github issues as well to keep an overview over the ideas and development needs.