php/archived-pie
1
0
Fork 0
mirror of https://github.com/php/pie.git synced 2026-03-23 23:12:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

Improve PIE developer documentation

Browse Source
This commit is contained in:
James Titcumb
2026-03-19 08:53:58 +00:00
parent 5175bec268
commit 37abd01c4d
5 changed files with 188 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
.github/ISSUE_TEMPLATE/bug_report.md vendored Normal file
View File

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

2
.github/workflows/continuous-integration.yml vendored
View File

@@ -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:

3
.gitignore vendored
View File

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

24
CONTRIBUTING.md
View File

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

152
docs/pie-maintainers-handbook.md
View File

@@ -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,