diff --git a/.travis.dist.yml b/.travis.dist.yml index 9ce10602..a2d7ebf9 100644 --- a/.travis.dist.yml +++ b/.travis.dist.yml @@ -26,7 +26,7 @@ php: env: global: - PGVER=13 - - MOODLE_BRANCH=MOODLE_311_STABLE + - MOODLE_BRANCH=MOODLE_402_STABLE matrix: - DB=pgsql - DB=mysqli @@ -40,7 +40,7 @@ before_install: # To use pcov for code coverage on Moodle 3.10 and up, install it using: # - pecl install pcov - cd ../.. - - composer create-project -n --no-dev --prefer-dist moodlehq/moodle-plugin-ci ci ^3 + - composer create-project -n --no-dev --prefer-dist moodlehq/moodle-plugin-ci ci ^4 - export PATH="$(cd ci/bin; pwd):$(cd ci/vendor/bin; pwd):$PATH" install: diff --git a/README.md b/README.md index 64af824b..36e6dac4 100644 --- a/README.md +++ b/README.md @@ -6,23 +6,23 @@ [![License](https://poser.pugx.org/moodlehq/moodle-plugin-ci/license)](//packagist.org/packages/moodlehq/moodle-plugin-ci) The goal of this project is to facilitate the running of tests and code -analysis against a Moodle plugin using CI environments, such as [Travis -CI](https://travis-ci.com) or [GitHub -Actions](https://docs.github.com/en/actions). All of these tests and tools +analysis against a Moodle plugin using CI environments, such as [GitHub +Actions](https://docs.github.com/en/actions) or [Travis +CI](https://travis-ci.com). All of these tests and tools are run everytime a change is pushed to a GitHub branch or pull request. * [Getting started](https://moodlehq.github.io/moodle-plugin-ci/) * [Help topics](https://moodlehq.github.io/moodle-plugin-ci/Help.html) * [Changelog](https://moodlehq.github.io/moodle-plugin-ci/CHANGELOG.html) -* [Upgrade 3.0](https://moodlehq.github.io/moodle-plugin-ci/UPGRADE-3.0.html) +* [Upgrade 4.0](https://moodlehq.github.io/moodle-plugin-ci/UPGRADE-4.0.html) History, acknowledgement and appreciation ========================================= -This repository is a fork of the original [moodle-plugin-ci](https://github.com/blackboard-open-source/moodle-plugin-ci), created -and maintained by **MoodleRooms** / **Blackboard** over the last years. All the licenses, copyrights and authorship of +This repository is a fork of [moodle-plugin-ci](https://github.com/blackboard-open-source/moodle-plugin-ci), originally created +and maintained by **MoodleRooms** / **Blackboard**. All the licenses, copyrights and authorship of the original code and commits have been kept unmodified, how not! -After some unsuccessful attempts over the last months to keep the product alive and maintained, +After some unsuccessful attempts along 2019-2020 to keep the product alive and maintained, proposing updates and fixes via standard pull requests, asking for some alternative collaboration schemas, and specially with the urgency of some changes to be implemented in order to keep the tool working with modern **Moodle** versions, it was decided, by **Moodle HQ**, to create this fork and take on its maintenance officially. diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 718380a7..7857b4e5 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -9,6 +9,23 @@ This project adheres to [Semantic Versioning](http://semver.org/). The format of this change log follows the advice given at [Keep a CHANGELOG](http://keepachangelog.com). ## [Unreleased] +### Added +- Upgrade guide: [Upgrading from 3.x to 4.0](UPGRADE-4.0.md) +- Support for PHP 8.1 and up. + +### Changed +- Lots of internals upgraded: + - [Symfony 5.4](https://symfony.com/releases/5.4). + - [PHPUnit 9.x](https://phpunit.de/announcements/phpunit-9.html). + - [Code coverage](https://app.codecov.io/gh/moodlehq/moodle-plugin-ci) reporting. + - [Psalm level 2](https://psalm.dev/docs/running_psalm/error_levels/) compliance. + - [PSR-12](https://www.php-fig.org/psr/psr-12/) compliance. +- Small changes to documentation towards prioritise GitHub Actions over Travis CI. +- In addition to the internal and doc changes above, this initial 4.x release has 100% feature-parity with current 3.x series, setting the base for further improvements and new features. No changes are expected in general, other than in order to meet the new requirements. + +### Removed +- Support for PHP < 7.4 (the new minimum version). +- Support for Moodle < 3.8.3, that was the [first release officially supporting PHP 7.4](https://moodledev.io/general/development/policies/php#php-74)). ## [3.4.12] - 2023-05-03 ### Changed @@ -267,7 +284,7 @@ The format of this change log follows the advice given at [Keep a CHANGELOG](htt ### Added - New help document: [CLI commands and options](CLI.md) -- Upgrade guide: [Upgrading from 2.X to 3.0](UPGRADE-3.0.md) +- Upgrade guide: [Upgrading from 2.x to 3.0](UPGRADE-3.0.md) ### Removed - Support for PHP 5.x (7.0.0 is now required). diff --git a/docs/GHAFileExplained.md b/docs/GHAFileExplained.md index 3d1bdc4a..e70ac9a1 100644 --- a/docs/GHAFileExplained.md +++ b/docs/GHAFileExplained.md @@ -38,11 +38,14 @@ jobs: ports: - 5432:5432 options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 3 + mariadb: image: mariadb:10 env: MYSQL_USER: 'root' MYSQL_ALLOW_EMPTY_PASSWORD: "true" + MYSQL_CHARACTER_SET_SERVER: "utf8mb4" + MYSQL_COLLATION_SERVER: "utf8mb4_unicode_ci" ports: - 3306:3306 options: --health-cmd="mysqladmin ping" --health-interval 10s --health-timeout 5s --health-retries 3 @@ -50,17 +53,13 @@ jobs: # Determines build matrix. This is a list of PHP versions, databases and # branches to test our project against. For each combination a separate # build will be created. For example below 6 builds will be created in - # total (7.3-pgsql, 7.3-mariadb, 7.4-pgsql, 7.4-mariadb, etc.). If we add + # total (7.4-pgsql, 7.4-mariadb, 8.0-pgsql, 8.0-mariadb, etc.). If we add # another branch, total number of builds will become 12. - # If you need to use PHP 7.0 and run phpunit coverage test, make sure you are - # using ubuntu-16.04 virtual environment in this case to have phpdbg or - # this version in the system. See the "Setup PHP" step below for more details - # about PHPUnit code coverage. strategy: fail-fast: false matrix: - php: ['7.3', '7.4', '8.0'] - moodle-branch: ['MOODLE_311_STABLE'] + php: ['7.4', '8.0', '8.1'] + moodle-branch: ['MOODLE_401_STABLE'] database: [pgsql, mariadb] # There is an alternative way allowing to define explicitly define which php, moodle-branch @@ -69,16 +68,13 @@ jobs: # matrix: # include: # - php: '8.0' - # moodle-branch: 'MOODLE_311_STABLE' + # moodle-branch: 'MOODLE_401_STABLE' # database: pgsql - # Optional line: Only needed if going to run php8 jobs and the plugin - # needs xmlrpc services or other special extensions. - # extensions: xmlrpc-beta - # - php: '7.4' - # moodle-branch: 'MOODLE_310_STABLE' + # - php: '8.0' + # moodle-branch: 'MOODLE_400_STABLE' # database: mariadb - # - php: '7.3' - # moodle-branch: 'MOODLE_39_STABLE' + # - php: '7.4' + # moodle-branch: 'MOODLE_311_STABLE' # database: pgsql steps: @@ -103,7 +99,7 @@ jobs: # locale, define nvm location. - name: Initialise moodle-plugin-ci run: | - composer create-project -n --no-dev --prefer-dist moodlehq/moodle-plugin-ci ci ^3 + composer create-project -n --no-dev --prefer-dist moodlehq/moodle-plugin-ci ci ^4 echo $(cd ci/bin; pwd) >> $GITHUB_PATH echo $(cd ci/vendor/bin; pwd) >> $GITHUB_PATH sudo locale-gen en_AU.UTF-8 diff --git a/docs/Help.md b/docs/Help.md index 990b4b3a..ce630d9d 100644 --- a/docs/Help.md +++ b/docs/Help.md @@ -88,6 +88,7 @@ There are few important options that you may want to use: ## Upgrade guides +* [Upgrading to Version 4](UPGRADE-4.0.md) * [Upgrading to Version 3](UPGRADE-3.0.md) * [Upgrading to Version 2](UPGRADE-2.0.md) diff --git a/docs/ReleaseNewVersion.md b/docs/ReleaseNewVersion.md index e2d2b339..64c04ee9 100644 --- a/docs/ReleaseNewVersion.md +++ b/docs/ReleaseNewVersion.md @@ -28,8 +28,8 @@ Once all code and commits are in place and verified, you need to tag a release. Tag `master` branch `HEAD` and push using commands: ```bash -$ git tag -a 3.1.0 -m "Release version 3.1.0" -$ git push origin 3.1.0 +$ git tag -a 4.0.8 -m "Release version 4.0.8" +$ git push origin 4.0.8 ``` (while it's also possible to use GitHub interface, we have decided not to do @@ -53,6 +53,6 @@ to be created manually. First build PHAR file manually: $ make build ``` -Once the above command suceeded, navigate to latest release in [GitHub +Once the above command succeeds, navigate to latest release in [GitHub interface](https://github.com/moodlehq/moodle-plugin-ci/releases), click "Edit" and attach generated PHAR file to release (you will find it at `./build` subdir). diff --git a/docs/TravisFileExplained.md b/docs/TravisFileExplained.md index 87c9c9f7..c39785f7 100644 --- a/docs/TravisFileExplained.md +++ b/docs/TravisFileExplained.md @@ -50,12 +50,12 @@ env: # socketed connections instead of localhost ones. - PGVER=13 # This line determines which version branch of Moodle to test against. - - MOODLE_BRANCH=MOODLE_311_STABLE + - MOODLE_BRANCH=MOODLE_402_STABLE # This matrix is used for testing against multiple databases. So for # each version of PHP being tested, one build will be created for each -# database listed here. EG: for PHP 7.3, one build will be created -# using PHP 7.3 and pgsql. In addition, another build will be created -# using PHP 7.3 and mysqli. +# database listed here. EG: for PHP 7.4, one build will be created +# using PHP 7.4 and pgsql. In addition, another build will be created +# using PHP 7.4 and mysqli. matrix: - DB=pgsql - DB=mysqli @@ -73,10 +73,10 @@ env: # jobs: # include: # - php: 8.0 -# env: MOODLE_BRANCH=MOODLE_311_STABLE DB=pgsql +# env: MOODLE_BRANCH=MOODLE_401_STABLE DB=pgsql +# - php: 8.0 +# env: MOODLE_BRANCH=MOODLE_400_STABLE DB=pgsql # - php: 7.4 -# env: MOODLE_BRANCH=MOODLE_311_STABLE DB=pgsql -# - php: 7.3 # env: MOODLE_BRANCH=MOODLE_311_STABLE DB=mysqli # .... # Note: this also enables to add specific env variables (NODE_VERSION, @@ -98,7 +98,7 @@ before_install: # directories to build the project. - cd ../.. # Install this project into a directory called "ci". - - composer create-project -n --no-dev --prefer-dist moodlehq/moodle-plugin-ci ci ^3 + - composer create-project -n --no-dev --prefer-dist moodlehq/moodle-plugin-ci ci ^4 # Update the $PATH so scripts from this project can be called easily. - export PATH="$(cd ci/bin; pwd):$(cd ci/vendor/bin; pwd):$PATH" diff --git a/docs/UPGRADE-2.0.md b/docs/UPGRADE-2.0.md index 77339ef5..113c0d13 100644 --- a/docs/UPGRADE-2.0.md +++ b/docs/UPGRADE-2.0.md @@ -1,6 +1,6 @@ --- layout: page -title: Upgrading from 1.X to 2.0 +title: Upgrading from 1.x to 2.0 --- This document outlines the steps one should take when upgrading to the new major version. diff --git a/docs/UPGRADE-3.0.md b/docs/UPGRADE-3.0.md index 1707ec25..61b34f23 100644 --- a/docs/UPGRADE-3.0.md +++ b/docs/UPGRADE-3.0.md @@ -1,6 +1,6 @@ --- layout: page -title: Upgrading from 2.X to 3.0 +title: Upgrading from 2.x to 3.0 --- This document outlines the steps one should take when upgrading to the new major version. diff --git a/docs/UPGRADE-4.0.md b/docs/UPGRADE-4.0.md new file mode 100644 index 00000000..fe72b4fb --- /dev/null +++ b/docs/UPGRADE-4.0.md @@ -0,0 +1,94 @@ +--- +layout: page +title: Upgrading from 3.x to 4.0 +--- + +This document outlines the steps one should take when upgrading to the new major version. + +## Step 1: Review the new requirements + +Requirements have changed, this project now requires **PHP 7.4 or later** and **Moodle 3.8.3** or later. + +## Step 2: Review the change log + +Detailed information about what changed in Version 4 can be found in the [change log](CHANGELOG.md). + +## Step 3: Review the CIs configuration files + +### GitHub Actions + +Review the updated [gha.dist.yml](https://github.com/moodlehq/moodle-plugin-ci/blob/master/gha.dist.yml) +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). + +A summary of the actions required for version 4 is: + +1. Change the `composer create-project` line and bump from version 3 (`^3`) to version 4 (`^4`). +2. Test it and, hopefully, party! + +### Travis CI + +Review the updated [.travis.dist.yml](https://github.com/moodlehq/moodle-plugin-ci/blob/master/.travis.dist.yml) +and update your `.travis.yml` file in your plugin. For detailed information about the contents of `.travis.dist.yml` +file, please see our [sample Travis workflow file explanation](TravisFileExplained.md). + +1. Change the `composer create-project` line and bump from version 3 (`^3`) to version 4 (`^4`). +2. Test it and, hopefully, party! + +## FAQ + +### What is happening to Version 3? + +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. + +### Why Version 4? + +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. + +### Can I run Version 3 and 4? + +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. + +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. + +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. + +For example, for GitHub Actions, it can be setup as follows: + +```yaml +# WARNING - this is only a partial example, +# several steps were excluded to keep it simple! + strategy: + fail-fast: false + matrix: + include: + - php: 8.2 + moodle-branch: master + database: pgsql + plugin-ci: ^4 # Decide the version to use per matrix element. + ... + ... + - php: 7.3 + moodle-branch: MOODLE_37_STABLE + database: mariadb + plugin-ci: ^3 # Decide the version to use per matrix element. + + ... + ... + steps: + - name: Check out repository code + uses: actions/checkout@v3 + with: + path: plugin + ... + ... + - name: Initialise moodle-plugin-ci + run: | + // Apply here for the configured plugin-ci version. + composer create-project -n --no-dev --prefer-dist moodlehq/moodle-plugin-ci ci ${{ matrix.plugin-ci }} + echo $(cd ci/bin; pwd) >> $GITHUB_PATH + echo $(cd ci/vendor/bin; pwd) >> $GITHUB_PATH + ... + ... +``` + +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. diff --git a/docs/index.md b/docs/index.md index ccf6c6ce..dbf350a7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -33,15 +33,15 @@ This project supports the following testing frameworks and code analysis tools: ## Requirements -The requirements for **Version 3** are **PHP 7.0** or later and **Moodle 3.2** or later. +The requirements for **Version 4** are **PHP 7.4** or later and **Moodle 3.8.3** or later. In addition, the plugin being tested must have a [version.php](https://docs.moodle.org/dev/version.php) file and `$plugin->component` must be defined within it. If you need to run your plugin in earlier versions of Moodle, then please use previous versions of this tool. Documentation -and more [information about Version 2 can be found here](https://github.com/moodlehq/moodle-plugin-ci/tree/2.5.0/docs/index.md). Similarly, [information about Version 1 can be found in here](https://github.com/moodlehq/moodle-plugin-ci/blob/1.5.8/README.md) +and more [information about Version 3 can be found here](https://github.com/moodlehq/moodle-plugin-ci/tree/3.x/docs/index.md). -Please know older versions (1 and 2) are no longer getting new features and may not receive additional updates. +Please know older versions (1, 2 and 3) are no longer getting new features and may not receive additional updates. ## Getting started @@ -97,6 +97,7 @@ Next steps on your continuous build journey may include: Guides to updating your plugin's `.travis.yml` file to use the latest versions of this tool. +* [Upgrade to 4.0](UPGRADE-4.0.md) * [Upgrade to 3.0](UPGRADE-3.0.md) * [Upgrade to 2.0](UPGRADE-2.0.md) diff --git a/gha.dist.yml b/gha.dist.yml index 86c619f4..4bf5202b 100644 --- a/gha.dist.yml +++ b/gha.dist.yml @@ -15,6 +15,7 @@ jobs: ports: - 5432:5432 options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 3 + mariadb: image: mariadb:10 env: @@ -22,7 +23,6 @@ jobs: MYSQL_ALLOW_EMPTY_PASSWORD: "true" MYSQL_CHARACTER_SET_SERVER: "utf8mb4" MYSQL_COLLATION_SERVER: "utf8mb4_unicode_ci" - ports: - 3306:3306 options: --health-cmd="mysqladmin ping" --health-interval 10s --health-timeout 5s --health-retries 3 @@ -30,8 +30,8 @@ jobs: strategy: fail-fast: false matrix: - php: ['7.3', '7.4', '8.0'] - moodle-branch: ['MOODLE_311_STABLE'] + php: ['7.4', '8.0', '8.1'] + moodle-branch: ['MOODLE_401_STABLE'] database: [pgsql, mariadb] steps: @@ -52,7 +52,7 @@ jobs: - name: Initialise moodle-plugin-ci run: | - composer create-project -n --no-dev --prefer-dist moodlehq/moodle-plugin-ci ci ^3 + composer create-project -n --no-dev --prefer-dist moodlehq/moodle-plugin-ci ci ^4 echo $(cd ci/bin; pwd) >> $GITHUB_PATH echo $(cd ci/vendor/bin; pwd) >> $GITHUB_PATH sudo locale-gen en_AU.UTF-8