|
| 1 | +--- |
| 2 | +layout: page |
| 3 | +title: Upgrading from 3.x to 4.0 |
| 4 | +--- |
| 5 | + |
| 6 | +This document outlines the steps one should take when upgrading to the new major version. |
| 7 | + |
| 8 | +## Step 1: Review the new requirements |
| 9 | + |
| 10 | +Requirements have changed, this project now requires **PHP 7.4 or later** and **Moodle 3.8.3** or later. |
| 11 | + |
| 12 | +## Step 2: Review the change log |
| 13 | + |
| 14 | +Detailed information about what changed in Version 4 can be found in the [change log](CHANGELOG.md). |
| 15 | + |
| 16 | +## Step 3: Review the CIs configuration files |
| 17 | + |
| 18 | +### GitHub Actions |
| 19 | + |
| 20 | +Review the updated [gha.dist.yml](https://github.com/moodlehq/moodle-plugin-ci/blob/master/gha.dist.yml) |
| 21 | +and update the GitHub Action workflow file in your plugin (for example, `.github/workflows/ci.yml`). For detailed information about the contents of that `ci.yml` file, please see our [sample GitHub Action workflow explanation](GHAFileExplained.md). |
| 22 | + |
| 23 | +A summary of the actions required for version 4 is: |
| 24 | + |
| 25 | +1. Change the `composer create-project` line and bump from version 3 (`^3`) to version 4 (`^4`). |
| 26 | +2. Test it and, hopefully, party! |
| 27 | + |
| 28 | +### Travis CI |
| 29 | + |
| 30 | +Review the updated [.travis.dist.yml](https://github.com/moodlehq/moodle-plugin-ci/blob/master/.travis.dist.yml) |
| 31 | +and update your `.travis.yml` file in your plugin. For detailed information about the contents of `.travis.dist.yml` |
| 32 | +file, please see our [sample Travis workflow file explanation](TravisFileExplained.md). |
| 33 | + |
| 34 | +1. Change the `composer create-project` line and bump from version 3 (`^3`) to version 4 (`^4`). |
| 35 | +2. Test it and, hopefully, party! |
| 36 | + |
| 37 | +## FAQ |
| 38 | + |
| 39 | +### What is happening to Version 3? |
| 40 | + |
| 41 | +Version 3 still exists within its own [3.x](https://github.com/moodlehq/moodle-plugin-ci/tree/3.x) branch. You can continue using it, but it is no longer getting new features and may not receive additional updates. In addition, it may start breaking in Moodle 4.3 or later, because of 8.2 incompatibilities. |
| 42 | + |
| 43 | +### Why Version 4? |
| 44 | + |
| 45 | +Mainly to be able to modernise all the internal components of the application which had remained largely unmodified since version 2. This will make it much easier to plan for the future and to leave behind very old versions of PHP (< 7.4) and Moodle (< 3.8.3), which have not been supported for a long time. |
| 46 | + |
| 47 | +### Can I run Version 3 and 4? |
| 48 | + |
| 49 | +If your plugin uses a single Git branch, but still works on Moodle versions older than 3.8.3, then you might want to try using both versions in a single GiHub Action or Travis file. |
| 50 | + |
| 51 | +First of all, this is not recommended due to its complexity. The preferred method is to use separate branches so your CI files are only using one version or another. |
| 52 | + |
| 53 | +Despite our recommendations, if you still want to run both versions in the same CI process, you can set environment variables to specify which version to use for every job. |
| 54 | + |
| 55 | +For example, for GitHub Actions, it can be setup as follows: |
| 56 | + |
| 57 | +```yaml |
| 58 | +# WARNING - this is only a partial example, |
| 59 | +# several steps were excluded to keep it simple! |
| 60 | + strategy: |
| 61 | + fail-fast: false |
| 62 | + matrix: |
| 63 | + include: |
| 64 | + - php: 8.2 |
| 65 | + moodle-branch: master |
| 66 | + database: pgsql |
| 67 | + plugin-ci: ^4 # Decide the version to use per matrix element. |
| 68 | + ... |
| 69 | + ... |
| 70 | + - php: 7.3 |
| 71 | + moodle-branch: MOODLE_37_STABLE |
| 72 | + database: mariadb |
| 73 | + plugin-ci: ^3 # Decide the version to use per matrix element. |
| 74 | + |
| 75 | + ... |
| 76 | + ... |
| 77 | + steps: |
| 78 | + - name: Check out repository code |
| 79 | + uses: actions/checkout@v3 |
| 80 | + with: |
| 81 | + path: plugin |
| 82 | + ... |
| 83 | + ... |
| 84 | + - name: Initialise moodle-plugin-ci |
| 85 | + run: | |
| 86 | + // Apply here for the configured plugin-ci version. |
| 87 | + composer create-project -n --no-dev --prefer-dist moodlehq/moodle-plugin-ci ci ${{ matrix.plugin-ci }} |
| 88 | + echo $(cd ci/bin; pwd) >> $GITHUB_PATH |
| 89 | + echo $(cd ci/vendor/bin; pwd) >> $GITHUB_PATH |
| 90 | + ... |
| 91 | + ... |
| 92 | +``` |
| 93 | +
|
| 94 | +The same can be also implemented for Travis CI jobs, adding the `plugin-ci` version as one more element in the jobs matrix `env` element. |
0 commit comments