search

catalyst / catalyst-moodle-workflows

4 stars 7 forks source link

readme

Reusable Workflows

Thanks to the new GitHub Actions feature called "Reusable Workflows" we can now reference an existing workflow with a single line of configuration rather than copying and pasting from one workflow to another.

This massively reduces the amount of boilerplate setup in each plugin to the bare minimum and also means that we can maintain and revise our definition of best practice in one place and have all the Moodle plugins inherit improvements in lock step. Mostly these shared actions in turn wrap the Moodle plugin CI scripts:

https://moodlehq.github.io/moodle-plugin-ci/

:rocket: Quick start

For most plugins, you'll want to go through this checklist:

  1. Ensure branch section in README.md describes correct versions supported
  2. Supported range in version.php has been configured correctly
  3. Workflow file has been added .github/workflows/ci.yml and configured
  4. CI badge has been properly added in the README.md

Some examples of usage: tool_mfa, tool_dataflows

Configure support range

Each plugin should have a measurable range of versions supported. It's recommended and ensures a predictable test range.

  1. Open version.php in your plugin repository
  2. Set the $plugin->supported* as the range the plugin supports, which then determines the versions the workflow tests for.
# version.php
$plugin->supported = [35, 402];

This example will run a matrix of tests from MOODLE_35_STABLE to MOODLE_402_STABLE - see full test matrix here.

Any number greater than the latest available stable branch will automatically include the master branch for testing

* For more info on the $plugin->supported field, please see https://docs.moodle.org/dev/version.php

Add the workflow

For most cases, this following demonstrates how your workflow file would typically look.

Create .github/workflows/ci.yml with the below template in your plugin repository.

# .github/workflows/ci.yml
name: ci

on: [push, pull_request]

jobs:
  ci:
    uses: catalyst/catalyst-moodle-workflows/.github/workflows/ci.yml@main
    # Required if you plan to publish (uncomment the below)
    # secrets:
      # moodle_org_token: ${{ secrets.MOODLE_ORG_TOKEN }}
    with:
      # Any further options in this section

For how to set up the secret, please see the How does this automate releases section below.

You can add extra options to disable checks that you might not want, or to add additional dependencies under the with field. For example:

    with:
      disable_behat: true
      disable_grunt: true
      extra_plugin_runners: 'moodle-plugin-ci add-plugin catalyst/moodle-local_aws'

with options

Below lists the available inputs which are all optional:

Inputs Description
codechecker_max_warnings To fail on warnings, set this to 0
extra_plugin_runners Command to install more dependencies
disable_behat Set true to disable behat tests.
disable_phpdoc Set true to disable phpdoc tests.
disable_phplint Set true to disable phplint tests.
disable_phpunit Set true to disable phpunit tests.
disable_grunt Set true to disable grunt.
disable_mustache Set true to disable mustache.
disable_master If true, this will skip testing against moodle/master branch
disable_release If true, this will skip the release job
disable_phpcpd If true, this will skip phpcpd checks
disable_ci_validate If true, this will skip moodle-plugin-ci validate checks
enable_phpmd If true, to enable phpmd
release_branches Name of the non-standardly named branch which should run the release job
moodle_branches Specify the MOODLE_XX_STABLE branch you specifically want to test against. This is not recommended, and instead you should configuring a supported range.
min_php The minimum php version to test. Set this to support the minimum php version supported by the plugin. Defaults to '7.1', however more recent Moodle branches only test higher versions.
ignore_paths Specify custom paths for CI to ignore. Third party libraries are ignored by default.

Add CI badge

With badges, we will be able to see at a glance from the plugin's README.md whether or not the plugin is in a good state for usage.

<a href="https://github.com/[USER]/[PLUGIN]/actions/workflows/ci.yml?query=branch%3A[BRANCH]">
<img src="https://github.com/[USER]/[PLUGIN]/workflows/ci/badge.svg?branch=[BRANCH]">
</a>

Please update [USER], [PLUGIN] and [BRANCH] in the example above. This goes under the plugin title. Here is an example:

<a href="https://github.com/catalyst/moodle-tool_excimer/actions/workflows/ci.yml?query=branch%3AMOODLE_35_STABLE">
<img src="https://github.com/catalyst/moodle-tool_excimer/workflows/ci/badge.svg?branch=MOODLE_35_STABLE">
</a>

which renders as:

How does this automate tests?

When you call the reusable ci, it will:

  1. a check to see what versions of moodle should run, based on the version.php file included in the plugin repository.
  2. This will then build out the combination of tests to run, performing the tests based on the MOODLE_XX_STABLE version affected and will handle any version specific caveats and run a more optimally configured test suite for you.

To view or modify the full matrix, please see it here: .github/actions/matrix/matrix_includes.yml

How does this automate releases?

Whenever a change is made to version.php, the workflow is triggered on a release branch (e.g. main / MOODLE_XX_STABLE), and tests pass, will it attempt to run the plugin/release action .github/plugin/release/action.yml. Doing so will automatically publish a release to the Moodle plugin directory at https://moodle.org/plugins.

In the prepare step of the CI, it will have resolved the component name for you so you don't need to enter one manually, and the MOODLE_ORG_TOKEN secret should be set otherwise the plugin won't be published.

To configure the secret:

Common concerns / issues

Core patches

If you need to apply core patches to the moodle code to allow the plugin to work on older versions missing API support, this can be achieved by outputting an appliable diff to a file, in the patch directory in the top level of the repo. The version for a particular branch should be named MOODLE_XX_STABLE.diff in line with the naming of the branch. To generate a diff, these patches can be manually applied to the target branch, and a diff from the remote generated by doing git format-patch MOODLE_XX_STABLE --stdout > my/plugin/path/patch/MOODLE_XX_STABLE.diff.

amd / grunt bundling issues

Depending on your supported range, you might encounter an issue which outputs something along the lines of File is stale and needs to be rebuilt. The brief reason for this, is that along the way, Moodle has updated the way it bundles JS/CSS files, which results in different outputs across Moodle versions.

To fix this, you'll need to rebundle the relevant files, on the highest supported version of Moodle for your plugin's support range. For example, if the plugin supports up to Moodle 4.0, you'll need to bundle the changes, while on the MOODLE_400_STABLE branch of Moodle, and then commit those changes.

NOTE: This may involve having a clean copy of Moodle and installing the plugin code to run the necessary commands to rebuild the stale files.

Grunt docs: https://docs.moodle.org/dev/Grunt#Running_grunt