Skip to content

pie-maintainers-handbook.md

Latest commit

 

History

History
303 lines (217 loc) · 11.6 KB

pie-maintainers-handbook.md

File metadata and controls

303 lines (217 loc) · 11.6 KB
Raw
title PIE Maintainers Handbook
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, 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 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.

PR Checklist

Caution

Completing the PR checklist is mandatory for all contributions.

## PR submitter checklist

- [ ] I have read [CONTRIBUTING.md](https://github.com/php/pie/blob/HEAD/CONTRIBUTING.md)
- [ ] I discussed this <bug|feature> with the maintainers in #<issue_number> (complete as appropriate)
- [ ] I have added appropriate tests
- [ ] I confirm that I have the right to submit this under the project's open source licence

This is to state that you have understood this contributing guide, and critically, that you have the right to submit the work under the project's open source licence; that is to say, it is your own original work.

Branching strategy

Since 1.3.0, we operate a branch per minor release, with an x for the patch version, for example, 1.3 series branch is named 1.3.x, 1.4 is named 1.4.x and so on. This allows releasing patch versions on older releases if a bug is found, for example.

New features

New feature branches should be based on the latest trunk (i.e. the default branch). Once merged, that feature will be part of the next minor release.

Bugfixes/Patches

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.

Architecture overview

Some key concepts are used in PIE;

  • Target PHP: PIE can be invoked like /path/to/php /path/to/pie ... or with pie --with-php-config=/path/to/php/config. This means that the PHP instance running PIE may not be the same PHP instance we're installing the extensions for. For example, if you're using Ondrej Sury's DEB installer, you could invoke /usr/bin/php8.4 /usr/local/bin/pie --with-php-config=/usr/bin/php-config7.2 which would run PIE with PHP 8.4, but compile and install the extension for the PHP 7.2 instance. In the code, this is represented by the \Php\Pie\Platform\TargetPhp\PhpBinaryPath class.
  • Target Platform: Along with the above Target PHP, the Target Platform describes other facets of the platform, such as OS, thread safety option, architecture (x86_64, x86, arm64, etc.). This is represented by the \Php\Pie\Platform\TargetPlatform class.

Entry point and DI

When running for development, bin/pie bootstraps a Symfony Console Application using Container::factory(), which wires everything with the Laravel/Illuminate Container.

This entrypoint is also used by the PHAR file when built.

Typical extension installation flow

The flow for resolving and installing an extension:

  1. Resolve – DependencyResolver (src/DependencyResolver/) uses Composer's solver via ResolveDependencyWithComposer to find a compatible ResolvedPackageRequest.
  2. Download – Composer's installer downloads/extracts the source. However, OverrideDownloadUrlInstallListener is is a Composer plugin listener that potentially changes the download URL, for example when using Windows, or the pre-built source or pre-built binary options are used.
  3. Build – Build (src/Building/) runs phpize + ./configure + make (UnixBuild) or uses the pre-built DLL on Windows (WindowsBuild), unless the pre-built binary option is used.
  4. Install – Install (src/Installing/) copies the .so/.dll and enables the extension in the INI via Ini\SetupIniApproach (picks the best strategy: phpenmod, docker-php-ext-enable, or direct INI edit).

This pipeline is coordinated by InstallAndBuildProcess (src/ComposerIntegration/InstallAndBuildProcess.php) called from Composer event listeners in src/ComposerIntegration/Listeners/.

The operation mode is tracked by the PieOperation enum (src/ComposerIntegration/PieOperation.php): Resolve, Download, Build, Install, Uninstall. PieComposerRequest carries this value plus target platform and configure options into the Composer run.

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:

sudo vendor/bin/phpunit

If you have multiple versions of PHP, you may add that in, e.g.:

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:

sudo XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-html coverage

Behaviour Testing

The primary features are documented in features/*.feature, in Gherkin format.

Some of these features are implemented as behaviour tests, using Behat. 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:

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:

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.

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 and several plugins to run static analysis on the codebase. You can run this:

vendor/bin/phpstan

Coding Standards

We use PHP_CodeSniffer using the Doctrine Coding Standard to check and automatically fix CS issues.

To check the CS conformity:

vendor/bin/phpcs

To attempt to auto-apply CS fixes:

vendor/bin/phpcbf

Classes marked @internal are not part of PIE's public API. Almost everything in the codebase should be marked as @internal, except things like exceptions. At this time PIE does not provide any extensibility or API surface to interact with.

As of PIE branch 1.5.x and newer, we use the library thecodingmachine/safe to throw exceptions instead of returning false when PHP functions are called. There is a static analysis rule in place to enforce this.

Mutation Testing

Install the infection.phar according to the Infection PHP documentation.

Tests can be run with:

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:

.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, one of:

# Using git reset (note: discards any local commits on `1.3.x`)
git checkout 1.3.x && git fetch upstream && git reset --hard upstream/1.3.x
# or, using git pull (note: use `--ff-only` to avoid making merge commits)
git checkout 1.3.x && git pull --ff-only upstream 1.3.x

Prepare a changelog, set the version and milestone to be released, e.g.:

PIE_VERSION=1.3.0
PIE_MILESTONE=$PIE_VERSION

Tip

For pre-releases, you can set the version/milestone to be different, e.g.:

PIE_VERSION=1.3.0-alpha.2
PIE_MILESTONE=1.3.0

This will tag/release with the 1.3.0-alpha.2 version, but will generate the changelog based on the 1.3.0 milestone in GitHub.

Then generate the changelog file:

composer require --dev -W jwage/changelog-generator --no-interaction
vendor/bin/changelog-generator generate --user=php --repository=pie --milestone=$PIE_MILESTONE > CHANGELOG-$PIE_VERSION.md
git checkout -- composer.*
composer install

Check you are happy with the contents of the changelog. Create a signed tag:

git tag -s $PIE_VERSION -F CHANGELOG-$PIE_VERSION.md
git push upstream $PIE_VERSION

The release pipeline will run, which will create a draft release, build the PHAR file, and attach it. You must then go to the draft release on GitHub, verify everything is correct, and publish the release.

rm CHANGELOG-$PIE_VERSION.md

Minor or Major releases: updating branches

Once a minor or major release is made, a new trunk should be created. For example, if you just released 1.3.0 from the 1.3.x branch, you should then create a new 1.4.x branch, and set that as the default.