Skip to content

Commit 6bc8f63

Browse files
stronk7stronk7
authored
Merge pull request #72 from kabalin/gha
Add GitHub Actions example and docs.
2 parents 22cc307 + 98ba7f5 commit 6bc8f63

File tree

7 files changed

+395
-20
lines changed

7 files changed

+395
-20
lines changed

‎README.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,11 @@
44
[![Total Downloads](https://poser.pugx.org/moodlehq/moodle-plugin-ci/downloads)](//packagist.org/packages/moodlehq/moodle-plugin-ci)
55
[![License](https://poser.pugx.org/moodlehq/moodle-plugin-ci/license)](//packagist.org/packages/moodlehq/moodle-plugin-ci)
66

7-
The goal of this project is to facilitate the running of tests and code analysis against a Moodle plugin in
8-
[Travis CI](https://travis-ci.com). All of these tests and tools are run everytime a change is pushed to a GitHub
9-
branch or pull request.
7+
The goal of this project is to facilitate the running of tests and code
8+
analysis against a Moodle plugin in CI tools, such as [Travis
9+
CI](https://travis-ci.com) or [GitHub
10+
Actions](https://docs.github.com/en/actions). All of these tests and tools
11+
are run everytime a change is pushed to a GitHub branch or pull request.
1012

1113
* [Getting started](https://moodlehq.github.io/moodle-plugin-ci/)
1214
* [Help topics](https://moodlehq.github.io/moodle-plugin-ci/Help.html)

‎docs/CHANGELOG.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ The format of this change log follows the advice given at [Keep a CHANGELOG](htt
1212
### Fixed
1313
- `moodle-plugin-ci grunt` now only runs against the `yui/src` directory when configuring the YUI task.
1414
This resolves an issue where an "Unable to find local grunt" message was reported when code was structured in a legacy
15-
format. See #46 for more details.
15+
format. See [#46](https://github.com/moodlehq/moodle-plugin-ci/issues/46) for more details.
1616

1717
### Changed
1818
- `moodle-plugin-ci phpunit` when coverage report is included, phpdbg is called with ignore memory limits param
@@ -21,7 +21,8 @@ The format of this change log follows the advice given at [Keep a CHANGELOG](htt
2121
- Updated version of [moodle-local_codechecker](https://github.com/moodlehq/moodle-local_codechecker) to v3.0.0.
2222

2323
### Added
24-
- Detect existence of legacy php-webdriver, and use a different Firefox image when it is in use
24+
- Detect existence of legacy php-webdriver, and use a different Firefox image when it is in use.
25+
- Add [manual](https://github.com/moodlehq/moodle-plugin-ci/blob/master/docs/index.md) and [example](https://github.com/moodlehq/moodle-plugin-ci/blob/master/docs/GHAFileExplained.md) on using GitHub Actions as CI tool.
2526

2627
## [3.0.3] - 2020-10-16
2728
### Changed

‎docs/GHAFileExplained.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
---
2+
layout: page
3+
title: GitHub Actions CI workflow file explained
4+
---
5+
6+
Below is the
7+
[gha.dist.yml](https://github.com/moodlehq/moodle-plugin-ci/blob/master/gha.dist.yml)
8+
file with comments added to explain what each section is doing. For additional
9+
information please refer to [workflow syntax reference](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions).
10+
11+
If you are familiar with Travis, it should be straightforward to understand
12+
the new syntax, also you may find this [migration
13+
manual](https://docs.github.com/en/actions/learn-github-actions/migrating-from-travis-ci-to-github-actions)
14+
useful.
15+
16+
```yaml
17+
# Title of the workflow
18+
name: Moodle Plugin CI
19+
20+
# Run this workflow every time a new commit pushed to your repository or PR
21+
# created.
22+
on: [push, pull_request]
23+
24+
jobs:
25+
# Set the job key. The key is displayed as the job name
26+
# when a job name is not provided
27+
test:
28+
# Virtual environment to use.
29+
runs-on: ubuntu-18.04
30+
31+
# DB services you need for testing.
32+
services:
33+
postgres:
34+
image: postgres:9.6
35+
env:
36+
POSTGRES_USER: 'postgres'
37+
POSTGRES_HOST_AUTH_METHOD: 'trust'
38+
ports:
39+
- 5432:5432
40+
options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 3
41+
mariadb:
42+
image: mariadb:10
43+
env:
44+
MYSQL_USER: 'root'
45+
MYSQL_ALLOW_EMPTY_PASSWORD: "true"
46+
ports:
47+
- 3306:3306
48+
options: --health-cmd="mysqladmin ping" --health-interval 10s --health-timeout 5s --health-retries 3
49+
50+
# Determines build matrix. This is a list of PHP versions, databases and
51+
# branches to test our project against. For each combination a separate
52+
# build will be created. For example below 6 builds will be created in
53+
# total (7.2-pgsql, 7.2-mariadb, 7.3-pgsql, 7.3-mariadb, etc.). If we add
54+
# another branch, total number of builds will become 12.
55+
# If you need to use PHP 7.0 and run phpunit coverage test, make sure you are
56+
# using ubuntu-16.04 virtual environment in this case to have phpdbg or
57+
# this version in the system.
58+
strategy:
59+
fail-fast: false
60+
matrix:
61+
php: ['7.2', '7.3', '7.4']
62+
moodle-branch: ['MOODLE_310_STABLE']
63+
database: [pgsql, mariadb]
64+
65+
# There is an alterantive way allowing to define explicitly define which php, moodle-branch
66+
# and database to use:
67+
#
68+
# matrix:
69+
# include:
70+
# - php: '7.4'
71+
# moodle-branch: 'MOODLE_310_STABLE'
72+
# database: pgsql
73+
# - php: '7.3'
74+
# moodle-branch: 'MOODLE_310_STABLE'
75+
# database: mariadb
76+
# - php: '7.2'
77+
# moodle-branch: 'MOODLE_39_STABLE'
78+
# database: pgsql
79+
80+
steps:
81+
# Check out this repository code in ./plugin directory
82+
- name: Check out repository code
83+
uses: actions/checkout@v2
84+
with:
85+
path: plugin
86+
87+
# Install PHP of required version. For possible options see https://github.com/shivammathur/setup-php
88+
- name: Setup PHP ${{ matrix.php }}
89+
uses: shivammathur/setup-php@v2
90+
with:
91+
php-version: ${{ matrix.php }}
92+
coverage: none
93+
94+
# Install this project into a directory called "ci", updating PATH and
95+
# locale.
96+
- name: Initialise moodle-plugin-ci
97+
run: |
98+
composer create-project -n --no-dev --prefer-dist moodlehq/moodle-plugin-ci ci ^3
99+
echo $(cd ci/bin; pwd) >> $GITHUB_PATH
100+
echo $(cd ci/vendor/bin; pwd) >> $GITHUB_PATH
101+
sudo locale-gen en_AU.UTF-8
102+
103+
# Run the default install.
104+
# Optionally, it is possible to specify a different Moodle repo to use
105+
# (git://github.com/moodle/moodle.git is used by default) and define
106+
# ignore directives or any other env vars for install step.
107+
#
108+
# env:
109+
# MOODLE_REPO=git://github.com/username/moodle.git
110+
# IGNORE_PATHS: 'ignore'
111+
# IGNORE_NAMES: 'ignore_name.php'
112+
# MUSTACHE_IGNORE_NAMES: 'broken.mustache'
113+
- name: Install moodle-plugin-ci
114+
run: |
115+
moodle-plugin-ci install --plugin ./plugin --db-host=127.0.0.1
116+
env:
117+
DB: ${{ matrix.database }}
118+
MOODLE_BRANCH: ${{ matrix.moodle-branch }}
119+
120+
# Steps that are run for the purpose of testing. Any of these steps
121+
# can be re-ordered or removed to your liking. And of course, you can
122+
# add any of your own custom steps.
123+
- name: PHP Lint
124+
if: ${{ always() }} # prevents CI run stopping if step failed.
125+
run: moodle-plugin-ci phplint
126+
127+
- name: PHP Copy/Paste Detector
128+
continue-on-error: true # This step will show errors but will not fail
129+
if: ${{ always() }}
130+
run: moodle-plugin-ci phpcpd
131+
132+
- name: PHP Mess Detector
133+
continue-on-error: true
134+
if: ${{ always() }}
135+
run: moodle-plugin-ci phpmd
136+
137+
- name: Moodle Code Checker
138+
if: ${{ always() }}
139+
run: moodle-plugin-ci codechecker --max-warnings 0
140+
141+
- name: Moodle PHPDoc Checker
142+
if: ${{ always() }}
143+
run: moodle-plugin-ci phpdoc
144+
145+
- name: Validating
146+
if: ${{ always() }}
147+
run: moodle-plugin-ci validate
148+
149+
- name: Check upgrade savepoints
150+
if: ${{ always() }}
151+
run: moodle-plugin-ci savepoints
152+
153+
- name: Mustache Lint
154+
if: ${{ always() }}
155+
run: moodle-plugin-ci mustache
156+
157+
- name: Grunt
158+
if: ${{ always() }}
159+
run: moodle-plugin-ci grunt --max-lint-warnings 0
160+
161+
- name: PHPUnit tests
162+
if: ${{ always() }}
163+
run: moodle-plugin-ci phpunit
164+
165+
- name: Behat features
166+
if: ${{ always() }}
167+
run: moodle-plugin-ci behat --profile chrome
168+
```

‎docs/Help.md‎

Lines changed: 71 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,83 @@ changed. Also a good place to look for new goodies.
1010

1111
## Help topics
1212

13-
* [Travis CI file explained](TravisFileExplained.md): every line of the `.travis.yml` file explained.
13+
* [Travis CI file explained](TravisFileExplained.md): every line of the `.travis.dist.yml` file explained.
14+
* [GitHub Actions workflow file explained](GHAFileExplained.md): every line of the `gha.dist.yml` file explained.
1415
* [Add extra Moodle configs](AddExtraConfig.md): how to add extra configs to Moodle `config.php`.
1516
* [Add extra plugins](AddExtraPlugins.md): how to add plugin dependencies to Moodle.
1617
* [Ignoring files](IgnoringFiles.md): how to ignore files that might be causing failures.
1718
* [Generating code coverage](CodeCoverage.md): how to generate code coverage of your plugin.
1819
* [CLI commands and options](CLI.md): the available `moodle-plugin-ci` commands and their options.
1920

21+
## Test steps quick start
22+
23+
Below is short reference to steps you may find useful to optimise set of test steps you want to
24+
inclide in the CI scenario. For detailed information, see [CLI commands and options](CLI.md) manual.
25+
26+
**moodle-plugin-ci phplint**
27+
28+
This step lints your PHP files to check for syntax errors.
29+
30+
**moodle-plugin-ci phpcpd**
31+
32+
This step runs the PHP Copy/Paste Detector on your plugin. This helps to find
33+
code duplication.
34+
35+
**moodle-plugin-ci phpmd**
36+
37+
This step runs the PHP Mess Detector on your plugin. This helps to find
38+
potential problems with your code which can result in refactoring
39+
opportunities.
40+
41+
**moodle-plugin-ci codechecker**
42+
43+
This step runs the Moodle Code Checker to make sure that your
44+
plugin conforms to the Moodle coding standards. It is highly recommended that
45+
you keep this step. To fail on warnings use `--max-warnings 0`
46+
47+
**moodle-plugin-ci phpdoc**
48+
49+
This step runs Moodle PHPDoc checker on your plugin.
50+
51+
**moodle-plugin-ci validate**
52+
53+
This step runs some light validation on the plugin file structure
54+
and code. Validation can be plugin specific.
55+
56+
**moodle-plugin-ci savepoints**
57+
58+
This step validates your plugin's upgrade steps.
59+
60+
**moodle-plugin-ci mustache**
61+
62+
This step validates the HTML and Javascript in your Mustache templates.
63+
64+
**moodle-plugin-ci grunt**
65+
66+
This step runs Grunt tasks on the plugin. By default, it tries to run tasks
67+
relevant to your plugin and Moodle version, but you can run specific tasks by
68+
passing them as options, e.g.: `moodle-plugin-ci grunt -t task1 -t task2` To
69+
fail on eslint warnings use `--max-lint-warnings 0`
70+
71+
**moodle-plugin-ci phpunit**
72+
73+
This step runs the PHPUnit tests of your plugin. If your plugin has
74+
PHPUnit tests, then it is highly recommended that you keep this step.
75+
76+
**moodle-plugin-ci behat**
77+
78+
This step runs the Behat tests of your plugin. If your plugin has
79+
Behat tests, then it is highly recommended that you keep this step.
80+
There are few important options that you may want to use:
81+
- The auto rerun option allows you to rerun failures X number of times,
82+
default is 2, EG usage: `--auto-rerun 3`
83+
- The dump option allows you to print the failure HTML to the console,
84+
handy for debugging, e.g. usage: `--dump`
85+
- The suite option allows you to set the theme to use for behat test. If
86+
not specified, the default theme is used, e.g. usage: `--suite boost`
87+
- The profile option allows you to set the browser driver to use,
88+
default is Firefox. If you need Chrome, set `--profile chrome`.
89+
2090
## Upgrade guides
2191

2292
* [Upgrading to Version 3](UPGRADE-3.0.md)

‎docs/ReleaseNewVersion.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,10 @@ Prior to tagging a release, ensure the following have been updated:
1010

1111
* The `CHANGELOG.md` needs to be up-to-date. In addition, the _Unreleased_ section needs to be updated
1212
with the version being released. Also update the _Unreleased_ link at the bottom with the new version number.
13-
* If this is a new major version, then the `.travis.dist.yml` and `doc/TravisFileExplained.md` need to be updated
14-
to use the new major version. Any other version will automatically be used.
13+
* If this is a new major version, then CI tool example files and its docs need
14+
to be updated to use the new major version (e.g. for Travis CI make changes
15+
in `.travis.dist.yml` and `doc/TravisFileExplained.md`). Any other version
16+
will automatically be used.
1517

1618
When all the changes above have been performed, push them straight upstream to
1719
`master` or create a standard PR to get them reviewed and incorporated

‎docs/index.md‎

Lines changed: 40 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,21 @@ layout: page
33
title: Introduction
44
---
55

6-
The goal of this project is to facilitate the running of tests and code analysis against a Moodle plugin in
7-
[Travis CI](https://travis-ci.com). All of these tests and tools are run everytime a change is pushed to a GitHub
8-
branch or pull request.
6+
The goal of this project is to facilitate the running of tests and code
7+
analysis against a Moodle plugin in CI tool of your choice. All of these tests
8+
and tools are run everytime a change is pushed to a GitHub branch or pull
9+
request.
10+
11+
We currently provide user manual how to use it with [Travis
12+
CI](https://travis-ci.com) and [GitHub
13+
Actions](https://docs.github.com/en/actions), if you are using
14+
`moodle-plugin-ci` with other CI services please do share your setup examples
15+
by creating a ticket.
916

1017
Why would you want to do this? It saves you from having to remember to setup and run PHPUnit, Behat, code checker, etc
1118
every single time you make a change. If you have enough test coverage, it also makes accepting pull requests painless
12-
because you can be more confident that the change wont break anything. There are many more advantages to using a
13-
service like Travis CI, like being able to test your code against multiple databases, multiple PHP versions, etc.
19+
because you can be more confident that the change wont break anything. There are many more advantages to use CI
20+
tools, like being able to test your code against multiple databases, multiple PHP versions, etc.
1421

1522
This project supports the following testing frameworks and code analysis tools:
1623
* [PHPUnit](https://phpunit.de)
@@ -37,31 +44,52 @@ Please know older versions (1 and 2) are no longer getting new features and may
3744

3845
## Getting started
3946

40-
Follow these steps to get your Moodle plugin building in Travis CI.
47+
Follow steps to get your Moodle plugin building in CI tool of your choice.
48+
49+
### Travis CI
4150

42-
### Step 1
51+
#### Step 1
4352

4453
Sign into [Travis CI](https://travis-ci.com) with your GitHub account. Once you’re signed in, and Travis CI will have
4554
synchronized your repositories from GitHub. Go to your [profile](https://travis-ci.com/profile) page and enable Travis CI
4655
for the plugin you want to build. Now whenever your plugin receives an update or gets a new pull request, Travis CI will
4756
run a build to make sure nothing broke.
4857

49-
### Step 2
58+
#### Step 2
5059

5160
Copy the [.travis.dist.yml](https://github.com/moodlehq/moodle-plugin-ci/blob/master/.travis.dist.yml) file into the
5261
root of your plugin and rename it to `.travis.yml`. Now might be a good time to review the `.travis.yml` contents and
5362
remove anything that is not needed. See this [help document](TravisFileExplained.md) for an explanation about the
5463
contents of the this file. Once you have added the `.travis.yml` file, commit and push up to GitHub, to trigger a
5564
Travis CI build. Navigate back to [Travis CI](https://travis-ci.com) to see if your build passes or fails.
5665

57-
### Step 3
66+
### GitHub Actions
67+
68+
#### Step 1
69+
70+
Copy [gha.dist.yml](https://github.com/moodlehq/moodle-plugin-ci/blob/master/gha.dist.yml) file to `.github/workflows` directory
71+
in your project. You can give this file any name, e.g. `moodle-ci.yml` which we use in this document. Review the `moodle-ci.yml` contents and
72+
remove anything that is not needed. See this [help document](GHAFileExplained.md) for an explanation about the
73+
contents of the this file. Once you have added the `.github/workflows/moodle-ci.yml` file, commit and push up to GitHub, to trigger a
74+
CI build.
75+
76+
#### Step 2
77+
78+
On GitHub, navigate to the main page of the repository. Under your repository
79+
name, click Actions tab and see your build status. You may find this [Quick
80+
Start manual](https://docs.github.com/en/actions/quickstart#viewing-your-workflow-results)
81+
useful. Now whenever you push commits to your plugin repo or it gets a new
82+
pull request, GitHub will run a build to make sure nothing broke.
83+
84+
### Getting more of CI
5885

59-
Congratulations, you are building on Travis CI! Next steps on your continuous build journey include:
86+
Next steps on your continuous build journey may include:
6087

6188
* Reviewing the [help documentation](Help.md) to further improve and customize your build.
62-
* Resolve any build errors you may currently have. Get to that ever rewarding Green Build status.
63-
* Show off your build status by [adding the badge to your plugin's README file](https://docs.travis-ci.com/user/status-images/).
89+
* Resolve any build errors you may currently have. Get to that ever rewarding Green Build status.
90+
* Show off your build status by adding the build status badge to your plugin's README file.
6491
* Write new tests to increase your code coverage.
92+
* Contribute to this repo if you have improvement idea or found an issue.
6593
* Enjoy your favorite beverage because you no longer have to waste time manually testing your plugin!
6694

6795
## Upgrading

0 commit comments

Comments
 (0)