From 5175bec268fb902c54e3e606d38cdcd1582dafc9 Mon Sep 17 00:00:00 2001 From: James Titcumb Date: Wed, 18 Mar 2026 12:57:26 +0000 Subject: [PATCH 1/3] Add mutation testing with Infection --- .github/workflows/continuous-integration.yml | 16 ++++++++++++++++ infection.json5 | 11 +++++++++++ 2 files changed, 27 insertions(+) create mode 100644 infection.json5 diff --git a/.github/workflows/continuous-integration.yml b/.github/workflows/continuous-integration.yml index 2c610d35..54ffeaa6 100644 --- a/.github/workflows/continuous-integration.yml +++ b/.github/workflows/continuous-integration.yml @@ -203,6 +203,22 @@ jobs: - name: Run phpstan run: vendor/bin/phpstan + mutation-testing: + runs-on: ubuntu-latest + steps: + - name: Setup PHP + uses: shivammathur/setup-php@v2 + with: + php-version: 8.4 + extensions: intl, sodium, zip + tools: infection + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + - uses: actions/checkout@v6 + - uses: ramsey/composer-install@v3 + - name: Run infection + run: sudo infection --min-msi=68 --min-covered-msi=68 --threads=4 --show-mutations=max --no-progress + build-assets: needs: - unit-tests diff --git a/infection.json5 b/infection.json5 new file mode 100644 index 00000000..c963786f --- /dev/null +++ b/infection.json5 @@ -0,0 +1,11 @@ +{ + "$schema": "https://raw.githubusercontent.com/infection/infection/0.32.6/resources/schema.json", + "source": { + "directories": [ + "src" + ] + }, + "mutators": { + "@default": true + } +} \ No newline at end of file From 37abd01c4da4f488b4f13a0018bdaed4d04ddd67 Mon Sep 17 00:00:00 2001 From: James Titcumb Date: Thu, 19 Mar 2026 08:53:58 +0000 Subject: [PATCH 2/3] Improve PIE developer documentation --- .github/ISSUE_TEMPLATE/bug_report.md | 31 ++++ .github/workflows/continuous-integration.yml | 2 +- .gitignore | 3 +- CONTRIBUTING.md | 24 +-- docs/pie-maintainers-handbook.md | 152 +++++++++++++++++++ 5 files changed, 188 insertions(+), 24 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 00000000..986ba413 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,31 @@ +--- +name: Bug report +about: Create a report to help us improve +title: '' +labels: '' +assignees: '' + +--- + +**What are you trying to do?** +Please describe what you are trying to do + +**What platform, and PIE version are you using?** +(add the output of `pie show -v`, and information about which OS you're using etc.) + +**Steps to reproduce the issue** +1. ... +2. ... +3. etc... + +**What do you expect to happen?** +Describe what you expect to see or happen. + +**What is actually happening** +Describe what is actually happening. + +**Complete logs/output** +Complete error messages and/or logs, including stack traces (hint: use `-v` for verbose), but _please redact sensitive information_. + +**Anything else?** +other information that might be helpful... diff --git a/.github/workflows/continuous-integration.yml b/.github/workflows/continuous-integration.yml index 54ffeaa6..9c041bd6 100644 --- a/.github/workflows/continuous-integration.yml +++ b/.github/workflows/continuous-integration.yml @@ -217,7 +217,7 @@ jobs: - uses: actions/checkout@v6 - uses: ramsey/composer-install@v3 - name: Run infection - run: sudo infection --min-msi=68 --min-covered-msi=68 --threads=4 --show-mutations=max --no-progress + run: sudo infection --min-msi=68 --min-covered-msi=68 --threads=max --show-mutations=max --no-progress build-assets: needs: diff --git a/.gitignore b/.gitignore index 1eb5695f..118b32b9 100644 --- a/.gitignore +++ b/.gitignore @@ -8,6 +8,7 @@ behat.yml box.json box.phar pie.phar +infection.phar /docs-package/ CHANGELOG-*.md -/.idea/ \ No newline at end of file +/.idea/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4a5c0e57..001899bb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,30 +1,10 @@ # Contributing to PIE -Thank you for taking an interest in contributing to PIE. - > [!IMPORTANT] > The TL;DR version of this is please either [open an issue](https://github.com/php/pie/issues) if you think you have > found a bug, or [create a discussion](https://github.com/php/pie/discussions) if you have an idea for a new feature, > **BEFORE** starting work on any code changes. Submitting a pull request without checking first may be duplicating > work that is already in progress! -## Reporting bugs - -If you think you have a bug, please [open an issue](https://github.com/php/pie/issues), and include: - - - What platform and PIE version you're using - - The steps to reproduce the issue - please use the `-v` verbose flag (or higher) - - Complete error messages and/or logs, including stack traces (hint: use `-v` for verbose), but please redact sensitive information - -## Submitting PRs - -Please **do not** just submit PRs for features or ideas without discussing them first. **Start by -[creating a discussion](https://github.com/php/pie/discussions) first** if there is not already an open discussion or -issue. If there is already an open discussion or issue, please comment and wait for feedback before starting any work. -This is because the work may already be in progress or being investigated already. The PIE project is actively being -developed, and many features are already in discussion or being developed, so if you do not discuss with us first, you -may be duplicating work already in progress. - -> [!TIP] -> We try to stay on top of issues already being worked on with the `maintainer investigating` purple label. If you see -> this on an issue, it is very likely we are already looking into this. +Please see the [PIE Maintainers Handbook](docs/pie-maintainers-handbook.md) for our full contributing guide and +documentation targeting contributors who want to work on PIE itself. diff --git a/docs/pie-maintainers-handbook.md b/docs/pie-maintainers-handbook.md index 64758f45..230afdb6 100644 --- a/docs/pie-maintainers-handbook.md +++ b/docs/pie-maintainers-handbook.md @@ -4,6 +4,35 @@ order: 3 --- # PIE Maintainers Handbook +Thank you for taking an interest in contributing to PIE. This guide is written to help humans develop on PIE. + +## Contributing to PIE + +## Reporting bugs + +If you think you have a bug, please [open an issue](https://github.com/php/pie/issues), and include: + + - What platform and PIE version you're using + - A summary of: + - What are you trying to do? + - What do you expect to happen? + - What is actually happening? + - The steps to reproduce the issue - please use the `-v` verbose flag (or higher) + - Complete error messages and/or logs, including stack traces (hint: use `-v` for verbose), but please redact sensitive information + +## Submitting PRs + +Please **do not** just submit PRs for features or ideas without discussing them first. **Start by +[creating a discussion](https://github.com/php/pie/discussions) first** if there is not already an open discussion or +issue. If there is already an open discussion or issue, please comment and wait for feedback before starting any work. +This is because the work may already be in progress or being investigated already. The PIE project is actively being +developed, and many features are already in discussion or being developed, so if you do not discuss with us first, you +may be duplicating work already in progress. + +> [!TIP] +> We try to stay on top of issues already being worked on with the `maintainer investigating` purple label. If you see +> this on an issue, it is very likely we are already looking into this. + ## Branching strategy Since 1.3.0, we operate a branch per minor release, with an `x` for the patch @@ -22,6 +51,129 @@ Bugfixes/patches should be based on the oldest supported or desired patch version. For example, if a bug affects the 1.3 series, a PR should be made from the feature branch to the `1.3.x` branch. +## Developing on PIE + +> [!IMPORTANT] +> Please read the above section BEFORE doing work on PIE; PIE is in very active development by the PHP Foundation, and +> many features/issues are already being worked on. + +All the below tests are run in CI, on various versions of PHP, to ensure they do not get missed! However, when +developing on PIE, you will likely need to run some, or all, of these tests by hand. + +> [!TIP] +> The development guide is primarily aimed at Linux systems, please adjust accordingly for your own platform. + +### Unit & Integration Tests + +> [!CAUTION] +> The integration test suite interacts directly with the PHP installation that is used to run the tests. This may +> result in the `asgrim/example-pie-extension` extension being added (sometimes in a broken state) to your PHP install. +> Do not run this using a PHP installation that you care about! + +We use PHPUnit, which is installed with Composer, and can be run with: + +```shell +sudo vendor/bin/phpunit +``` + +If you have multiple versions of PHP, you may add that in, e.g.: + +```shell +sudo /usr/bin/php8.3 vendor/bin/phpunit +``` + +> [!TIP] +> `sudo` **is** required due to the way some of the tests interact with `sudo` + +Coverage HTML report can be generated with: + +```shell +sudo XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-html coverage +``` + +### Behaviour Testing + +The primary features are documented in `features/*.feature`, in [Gherkin](https://cucumber.io/docs/gherkin/) format. + +Some of these features are implemented as behaviour tests, using [Behat](https://behat.org/). However, these tests +should NOT be run on your machine directly. Instead, there is a predefined and controlled environment made with Docker. +This is done because many of the tests require specific dependencies, and this helps provide a repeatable test harness. + +This can be run in two steps; first build the Docker container: + +```shell +GITHUB_TOKEN=$(composer config --global --auth github-oauth.github.com) docker buildx build --file .github/pie-behaviour-tests/Dockerfile --secret id=GITHUB_TOKEN,env=GITHUB_TOKEN -t pie-behat-test . +``` + +Optionally, pass the `--build-arg PHP_VERSION=8.3` parameter to the above command to change the version of PHP used in +the test. Then you may run the tests with: + +```shell +docker run --volume .:/github/workspace -ti pie-behat-test +``` + +### End-to-end Testing + +We have a small number of end-to-end type tests, that are designed to ensure PIE runs in particular ways in different +systems. The test runner is a shell script that builds a Docker target, and runs it; and fails if a non-zero exit +occurs. + +```shell +test/end-to-end/dockerfile-e2e-test.sh +``` + +This is particularly useful for testing different setups (e.g. Alpine, Ubuntu, Fedora, Brew, etc.) and ensuring build +tools and system dependencies are automatically installed. + +### Static Analysis + +We use [PHPStan](https://phpstan.org/) and several plugins to run static analysis on the codebase. You can run this: + +```shell +vendor/bin/phpstan +``` + +### Coding Standards + +We use [PHP_CodeSniffer](https://github.com/PHPCSStandards/PHP_CodeSniffer/) using the +[Doctrine Coding Standard](https://github.com/doctrine/coding-standard) to check and automatically fix CS issues. + +To check the CS conformity: + +```shell +vendor/bin/phpcs +``` + +To attempt to auto-apply CS fixes: + +```shell +vendor/bin/phpcbf +``` + +### Mutation Testing + +Install the `infection.phar` according to the [Infection PHP documentation](https://infection.github.io/guide/installation.html#Phar). + +Tests can be run with: + +```shell +sudo infection --min-msi=68 --min-covered-msi=68 --threads=max +``` + +> [!TIP] +> As with the tests, `sudo` is required due to the way some of the tests interact with `sudo` + +### Documentation + +Documentation can be generated with: + +```shell +.github/docs/build-docs.sh +``` + +This is not normally needed, unless you are changing the template, as CI will generate the documentation and publish to +the GitHub Page. + ## Release process Make sure you have the latest version of the trunk to be released, for example, From cbbe697859f2b2b6ae4f5889096890f801053a67 Mon Sep 17 00:00:00 2001 From: James Titcumb Date: Thu, 19 Mar 2026 10:39:22 +0000 Subject: [PATCH 3/3] Ensure mutation tests have GH token --- .github/workflows/continuous-integration.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/continuous-integration.yml b/.github/workflows/continuous-integration.yml index 9c041bd6..3276779a 100644 --- a/.github/workflows/continuous-integration.yml +++ b/.github/workflows/continuous-integration.yml @@ -217,6 +217,8 @@ jobs: - uses: actions/checkout@v6 - uses: ramsey/composer-install@v3 - name: Run infection + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: sudo infection --min-msi=68 --min-covered-msi=68 --threads=max --show-mutations=max --no-progress build-assets: