Merge pull request #19 from stronk7/add_v2_to_v3_docs

Initial preparations for version 3.

Author: kabalin

.travis.dist.yml

@@ -16,6 +16,7 @@ cache:
 php:
  - 7.2
  - 7.3
+ - 7.4
 
 env:
  global:
@@ -27,7 +28,7 @@ env:
 before_install:
   - phpenv config-rm xdebug.ini
   - cd ../..
-  - composer create-project -n --no-dev --prefer-dist moodlehq/moodle-plugin-ci ci ^2
+  - composer create-project -n --no-dev --prefer-dist moodlehq/moodle-plugin-ci ci ^3
   - export PATH="$(cd ci/bin; pwd):$(cd ci/vendor/bin; pwd):$PATH"
 
 install:

composer.json

@@ -5,6 +5,12 @@
   "type": "project",
   "license": "GPL-3.0-or-later",
   "authors": [
+    {
+      "name": "Ruslan Kabalin",
+      "email": "[email protected]",
+      "homepage": "https://moodle.com",
+      "role": "Maintainer"
+    },
     {
       "name": "Mark Nielsen",
       "email": "[email protected]",
@@ -18,6 +24,11 @@
       "role": "Developer"
     }
   ],
+  "support": {
+    "issues": "https://github.com/moodlehq/moodle-plugin-ci/issues",
+    "source": "https://github.com/moodlehq/moodle-plugin-ci",
+    "docs": "https://moodlehq.github.io/moodle-plugin-ci/"
+  },
   "repositories": [
     {
       "type": "package",

docs/CHANGELOG.md

@@ -10,17 +10,18 @@ The format of this change log follows the advice given at [Keep a CHANGELOG](htt
 
 ## [Unreleased]
 ### Changed
-- TODO: Document all the changes to jump to this new release from previous 2.5.0, similarly to the docs explaining 1.x => 2.x changes.
 - ACTION REQUIRED: project organization renamed to moodlehq. You must update your `.travis.yml` to use `moodlehq/moodle-plugin-ci`
-- Updated [.travis.dist.yml] with a new `services` section to ensure databases start.
-- Updated [.travis.dist.yml] to remove `openjdk-8-jre-headless` and updated `moodlehq/moodle-local_ci` to fix Mustache linting. See [moodle-local_ci/pull#198](https://github.com/moodlehq/moodle-local_ci/pull/198).
-- `moodle-plugin-ci behat` is using Selenium docker container for built-in Selenium server.
 - ACTION REQUIRED: If you initiated Selenium server in docker container as
   part of your test scenario (e.g. separate step in install stage similar to
   one outlined in workaround
   [blackboard-open-source/issue#110](https://github.com/blackboard-open-source/moodle-plugin-ci/issues/110)),
   this is no longer required, you can remove this step.
-- Updated version of `moodlehq/moodle-local_codechecker` to v2.9.6
+- ACTION REQUIRED: You may safely remove `nvm install <version>` and `nvm use
+  <version>` from .travis.yml, this is now a part of installation routine.
+- Updated [.travis.dist.yml] with a new `services` section to ensure databases start.
+- Updated [.travis.dist.yml] to remove `openjdk-8-jre-headless` and updated `moodlehq/moodle-local_ci` to fix Mustache linting. See [moodle-local_ci/pull#198](https://github.com/moodlehq/moodle-local_ci/pull/198).
+- `moodle-plugin-ci behat` is using Selenium docker container for built-in Selenium server.
+- Updated version of `moodlehq/moodle-local_codechecker` to v2.9.7
 - Updated [.travis.dist.yml] to build Moodle 3.9
 - `moodle-plugin-ci install` installs Node.js (npm) using the version
   specified in .nvmrc file or `lts/carbon` if .nvmrc is missing (pre Moodle
@@ -29,8 +30,6 @@ The format of this change log follows the advice given at [Keep a CHANGELOG](htt
   this parameter should be compatible with `nvm install` command,
   e.g. `v8.9`, `8.9.0`, `lts/erbium`. See
   [#7](https://github.com/moodlehq/moodle-plugin-ci/issues/7)
-- ACTION REQUIRED: You may safely remove `nvm install <version>` and `nvm use
-  <version>` from .travis.yml, this is now a part of installation routine.
 
 ### Added
 - New help document: [CLI commands and options](CLI.md)

docs/TravisFileExplained.md

@@ -15,12 +15,13 @@ language: php
 addons:
   postgresql: "9.5"
 
-# Ensure DB services are running.
+# Ensure DB and docker services are running.
 services:
   - mysql
   - postgresql
+  - docker
 
-# Cache NPM's and Composer's caches to speed up build times.
+# Cache Composer's and NPM's caches to speed up build times.
 cache:
   directories:
     - $HOME/.composer/cache
@@ -32,6 +33,7 @@ cache:
 php:
  - 7.2
  - 7.3
+ - 7.4
 
 # This section sets up the environment variables for the build.
 env:
@@ -51,6 +53,22 @@ env:
 # (git://github.com/moodle/moodle.git is used by default):
 # - MOODLE_REPO=git://github.com/username/moodle.git
 
+# Also, note that, for multi-branch scenarios, where the same plugin
+# codebase needs to be tested against multiple branches of Moodle,
+# it is possible to remove the `php`, `env/global`, and `matrix`
+# sections above and just create a `jobs` section explicitly defining
+# which `php`, `MOODLE_BRANCH` and `DB` to use, for example:
+#
+# jobs:
+#   include:
+#     - php: 7.3
+#       env: MOODLE_BRANCH=MOODLE_39_STABLE    DB=psql
+#     - php: 7.3
+#       env: MOODLE_BRANCH=MOODLE_39_STABLE    DB=mysqli
+#     ....
+# Note: this also enables to add specific env variables (NODE_VERSION,
+# EXTRA_PLUGINS...) per job, if you don't want to do it globally.
+
 # This lists steps that are run before the installation step.
 before_install:
 # This disables XDebug which should speed up the build.
@@ -59,7 +77,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/plugin-ci ci ^2
+  - composer create-project -n --no-dev --prefer-dist moodlehq/plugin-ci ci ^3
 # Update the $PATH so scripts from this project can be called easily.
   - export PATH="$(cd ci/bin; pwd):$(cd ci/vendor/bin; pwd):$PATH"
 
@@ -71,6 +89,7 @@ install:
 #    - Create Moodle config.php, database, etc.
 #    - Copy your plugin(s) into Moodle.
 #    - Run Composer install within Moodle.
+#    - Install the correct (or configured) version of nodejs/npm using NVM.
 #    - Run NPM install in Moodle and in your plugin if it has a "package.json".
 #    - Run "grunt ignorefiles" within Moodle to update ignore file lists.
 #    - If your plugin has Behat features, then Behat will be setup.

docs/UPGRADE-2.0.md

@@ -25,7 +25,7 @@ upgrade of NodeJS, etc.
 
 ### What is happening to Version 1?
 
-Version 1 still exists in the [v1](https://github.com/moodlehq/moodle-plugin-ci/tree/v1) branch.  You can continue
+Version 1 still exists as its last release [1.5.8](https://github.com/moodlehq/moodle-plugin-ci/tree/1.5.8).  You can continue
 to use it, but it is no longer getting new features and may not receive additional updates.  In addition, it may start
 breaking in Moodle 3.2 or later.
 

docs/UPGRADE-3.0.md

@@ -0,0 +1,79 @@
+---
+layout: page
+title: Upgrading from 2.X to 3.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.0 or later and Moodle 3.2 or later.
+
+## Step 2: Review the change log
+
+Detailed information about what changed in Version 3 can be found in the [change log](CHANGELOG.md).
+
+## Step 3: Review the Travis CI configuration file
+
+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 this [help document](TravisFileExplained.md).  **Please carefully** review the updated
+`.travis.dist.yml` as some steps have been removed and others added, like installation of Java 8,
+upgrade of NodeJS, etc.
+
+A summary of the actions required may be:
+
+1. Move to `moodlehq/moodle-plugin-ci` and bump to version 3 (^3).
+2. Ensure that the `docker` service is available.
+3. Remove any use of selenium or browsers, now they are handled automatically  using docker images.
+4. Remove any use of manual `nvm`, `node` or `npm` stuff (unless it's to install components specific for your plugin). Now that's handled automatically too.
+
+Note: Still, it's possible to configure the `node` version to be used, in case you want to experiment or have any exact need for a given plugin or branch. This is how it works, in order of precedence, fall-backing to next:
+
+1. `--node-version` (install option).
+2. `NODE_VERSION` (env variable).
+3. `.nvmrc` (file present since Moodle 3.5).
+4. `lts/carbon` (last resort, default/legacy before Moodle 3.5).
+
+## FAQ
+
+### What is happening to Version 2?
+
+Version 2 still exists as its last release [2.5.0](https://github.com/moodlehq/moodle-plugin-ci/tree/2.5.0).  You can continue
+to use it, but it is no longer getting new features and may not receive additional updates.  In addition, it may start breaking in Moodle 3.10 or later.
+
+### Why Version 3?
+
+Mainly to clearly separate development from the original [moodle-plugin-ci](https://github.com/blackboard-open-source/moodle-plugin-ci) as explained [here](https://github.com/moodlehq/moodle-plugin-ci#history-acknowledgement-and-appreciation). Also because, since **Moodle 3.5** we have a better way to control different node/npm versions using [nvm](https://github.com/nvm-sh/nvm) automatically. Finally because we wanted to leave PHP 5.x behind once and forever and this was a good moment to force the jump to **PHP 7**.
+
+### Can I run Version 1 and 3?
+
+If your plugin uses a single Git branch, but still works on Moodle versions older than 3.2, then you might be wanting
+to try to use both versions in a single `.travis.yml` file.  First, this is not recommended due to its complexity.
+The preferred method is to use separate branches so your `.travis.yml` file is only using one version or another.
+If that is not desirable, then one could go about it by using environment variables.  First, be sure that you update
+your `.travis.yml` file as explained above.  Then a rough and **untested** example might be:
+
+```yaml
+# WARNING - this is only a partial example, several steps were excluded to keep it simple!
+
+env:
+  # Define a V3 flag to conditionally run commands.
+  - MOODLE_BRANCH=MOODLE_31_STABLE DB=pgsql V3=false
+  - MOODLE_BRANCH=MOODLE_32_STABLE DB=mysqli V3=true
+
+before_install:
+  # You must install the correct version of this project:
+  - if [ "$V3" = false ]; then composer create-project -n --no-dev --prefer-dist moodlehq/moodle-plugin-ci ci ^1; fi
+  - if [ "$V3" = true ]; then composer create-project -n --no-dev --prefer-dist moodlehq/moodle-plugin-ci ci ^3; fi
+
+script:
+  # Example of a Version 3 execution:
+  - if [ "$V3" = true ]; then ...; fi
+
+  # Example of a Version 1 execution:
+  - if [ "$V3" = false ]; then ...; fi
+
+  # And of course some exist in both versions, so just call it normally:
+  - moodle-plugin-ci phpunit
+```

docs/index.md

@@ -25,14 +25,15 @@ This project supports the following testing frameworks and code analysis tools:
 
 ## Requirements
 
-The requirements for **Version 2** are **PHP 5.6** or later and **Moodle 3.2** or later.
+The requirements for **Version 3** are **PHP 7.0** or later and **Moodle 3.2** 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 Version 1 of this tool.  Documentation
-and more information about Version 1 can be found in the [v1](https://github.com/moodlehq/moodle-plugin-ci/tree/v1)
-branch.  Please know that Version 1 is no longer getting new features and may not receive additional updates.
+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)
+
+Please know older versions (1 and 2) are no longer getting new features and may not receive additional updates.
 
 ## Getting started
 
@@ -67,6 +68,7 @@ Congratulations, you are building on Travis CI!  Next steps on your continuous b
 
 Guides to updating your plugin's `.travis.yml` file to use the latest versions of this tool.
 
+* [Upgrade to 3.0](UPGRADE-3.0.md)
 * [Upgrade to 2.0](UPGRADE-2.0.md)
 
 ## Documentation