Add mutation testing with Infection

.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...

.github/workflows/continuous-integration.yml

@@ -203,6 +203,24 @@ 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
+        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:
     needs:
       - unit-tests

.gitignore

@@ -8,6 +8,7 @@ behat.yml
 box.json
 box.phar
 pie.phar
+infection.phar
 /docs-package/
 CHANGELOG-*.md
-/.idea/
+/.idea/

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.

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,

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
+    }
+}