Skip to content

Commit 2b34299

Browse files
iMattProiMattPro
committed
Update readme
1 parent dd55262 commit 2b34299

1 file changed

Lines changed: 71 additions & 24 deletions

File tree

‎README.md‎

Lines changed: 71 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,19 @@ Reusable GitHub Actions workflow for testing phpBB extensions across multiple en
44

55
This repository contains a pre-configured test workflow designed for phpBB extension developers. It runs your extension's tests using various PHP versions and database systems, including **MySQL**, **PostgreSQL**, **SQLite**, and **Microsoft SQL Server**.
66

7-
## 🚀 Features
7+
## Table of Contents
8+
9+
- [✨ Features](#-features)
10+
- [🚀 How to Use](#-how-to-use)
11+
- [🧪 Branches](#-branches)
12+
- [✅ Requirements](#-requirements)
13+
- [⏭️ Skipping Jobs](#️-skipping-jobs)
14+
- [📦 Dependency Installation](#-dependency-installation)
15+
- [⚙️ Customising the PHP Test Suite](#️-customising-the-php-test-suite)
16+
- [📊 Code Coverage with Codecov](#-code-coverage-with-codecov)
17+
- [📄 License](#-license)
18+
19+
## ✨ Features
820

921
- Supports **PHP 7.2+** through **8.x**
1022
- Tests against multiple database engines
@@ -15,14 +27,7 @@ This repository contains a pre-configured test workflow designed for phpBB exten
1527
- Executable files
1628
- Code coverage via Codecov
1729

18-
## 🧪 Branches
19-
20-
- `3.3.x`: Targets the **phpBB 3.3.x** release line.
21-
- `master`: Targets the latest development version of **phpBB** (`master` branch).
22-
23-
Use the branch that matches the phpBB version you're developing for.
24-
25-
## 📦 How to Use
30+
## 🚀 How to Use
2631

2732
On GitHub.com, go to your extension's repository, click **Add file → Create new file**, name it `.github/workflows/tests.yml`, add the workflow content shown below, and commit the file. Make sure to replace `acme/demo` with your actual extension vendor/package name, and optionally you may adjust any of the branch names and other checks.
2833

@@ -58,11 +63,22 @@ jobs:
5863
CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} # Do not edit this
5964
```
6065
66+
## 🧪 Branches
67+
68+
Use the branch that matches the phpBB version you're developing for.
69+
70+
- `3.3.x`: Targets the **phpBB 3.3.x** release line.
71+
- `master`: Targets the latest development version of **phpBB** (`master` branch).
72+
6173
## ✅ Requirements
6274

6375
- Your extension's package contents must be located at the root level of the repository. That is, the repository **must directly represent the package**, with all relevant files such as `composer.json`, `README`, `LICENSE`, etc. placed directly in the **root of the repository**, **not inside a subdirectory within the repository**. See any of phpbb-extension's official extension repositories as an example.
6476
- Tests must be defined in your repository using PHPUnit.
6577

78+
# Advanced Configuration Options
79+
80+
The following sections provide instruction for advanced users who are not able to use the default workflow out-of-the-box configuration. If your tests are failing with the default workflow, it may be because you need to change the PHP versions or skip certain jobs.
81+
6682
## ⏭️ Skipping Jobs
6783

6884
This test framework runs four primary job groups:
@@ -71,7 +87,7 @@ This test framework runs four primary job groups:
7187
3. PostgreSQL - Tests using PostgreSQL database structures.
7288
4. MSSQL - Tests using MSSQL and SQLite3 database structures.
7389

74-
You can skip any of these job groups—such as if your extension does not support MSSQL—by setting the appropriate arguments when using this workflow:
90+
You can skip any of these job groups—such as if your extension does not support MSSQL—by setting the appropriate optional arguments when using this workflow:
7591

7692
```yaml
7793
with:
@@ -85,6 +101,40 @@ with:
85101

86102
> Note: If you do not need to skip any jobs, you don’t need to include these arguments at all. For example, omitting `RUN_BASIC_JOBS` is equivalent to setting it to 1. You only need to define these arguments if you want to disable a job by setting its value to 0.
87103

104+
## 📦 Dependency Installation
105+
106+
If your extension requires **NPM** or **Composer** dependencies, you can enable automatic installation by setting the following arguments:
107+
108+
```yaml
109+
with:
110+
...
111+
RUN_NPM_INSTALL: 1 # Set to 1 to run `npm ci`; otherwise set to 0 or omit
112+
RUN_COMPOSER_INSTALL: 1 # Set to 1 to run `composer install`; otherwise set to 0 or omit
113+
...
114+
```
115+
116+
> 💡 If you don't need either, you can omit these arguments entirely.
117+
118+
## ⚙️ Customising the PHP Test Suite
119+
120+
By default, this framework tests your extension against the full range of PHP versions supported by phpBB (7.2 through 8.4). You can override this by specifying the following optional inputs:
121+
122+
```yaml
123+
with:
124+
...
125+
PRIMARY_PHP_VERSION: '8.1'
126+
PHP_VERSION_MATRIX: '["8.0", "8.1", "8.2", "8.3", "8.4"]'
127+
...
128+
```
129+
130+
- `PRIMARY_PHP_VERSION`: The PHP version used for **all** jobs, including code checks and database tests. Defaults to `7.2`.
131+
- `PHP_VERSION_MATRIX`: A JSON array of PHP versions to test against during **MySQL** and **PostgreSQL** jobs. Defaults to:
132+
```json
133+
["7.2", "7.3", "7.4", "8.0", "8.1", "8.2", "8.3", "8.4"]
134+
```
135+
136+
> 💡 Use these options if your extension supports only a specific set of PHP versions, or if you want to test against a narrower or newer PHP version range.
137+
88138
## 📊 Code Coverage with Codecov
89139

90140
This test framework supports code coverage reporting through [Codecov.io](https://codecov.io). To enable it, follow these steps:
@@ -100,16 +150,24 @@ fixes:
100150
101151
Make sure to replace `acme/demo` with your actual extension vendor/package name.
102152

103-
### 2. Sign in to Codecov
153+
### 2. Enable Codecov in the Workflow
104154

105-
- Visit [https://codecov.io](https://codecov.io)
106-
- Log in with your **GitHub** account
155+
Ensure `CODECOV: 1` is set in your workflow call:
156+
157+
```yaml
158+
with:
159+
...
160+
CODECOV: 1
161+
...
162+
```
107163

108164
### 3. Get Your Codecov Token (if required)
109165

110166
Most public repositories do **not** require a token.
111167
For private repositories or certain CI setups, you may need a global **Codecov token**:
112168

169+
- Visit [https://codecov.io](https://codecov.io)
170+
- Log in with your **GitHub** account
113171
- Go to your [Codecov account settings](https://app.codecov.io/account/token)
114172
- Copy the token
115173

@@ -119,17 +177,6 @@ Then, in your GitHub repository:
119177
- Click **"New repository secret"**
120178
- Name it `CODECOV_TOKEN` and paste your token value
121179

122-
### 4. Enable Codecov in the Workflow
123-
124-
Ensure `CODECOV: 1` is set in your workflow call:
125-
126-
```yaml
127-
with:
128-
...
129-
CODECOV: 1
130-
...
131-
```
132-
133180
Once set up, Codecov will automatically collect and display coverage reports for your extension after each test run.
134181

135182
> 💡 You can view your coverage reports and badges by visiting your extension's page on [Codecov.io](https://codecov.io).

0 commit comments

Comments
 (0)