Contribution

Contributions are welcome. This chapter describes how to set up a development environment, how to run the tests and quality checks, and the commit message rules used in this repository.

The source code and issue tracker are hosted on GitHub: fgtclb/environment-state-manager.

Development environment

All tests and quality tools run in containers through the Build/Scripts/runTests.sh wrapper. The only requirement on the host is a container runtime – podman (preferred) or docker. The wrapper pulls the required TYPO3 testing images on first use; nothing else is installed on the host.

Dependencies are installed into the git-ignored .Build/ directory. The wrapper installs them for a specific TYPO3 core and PHP version:

# Install dependencies for TYPO3 v13 on PHP 8.2 (default matrix).
Build/Scripts/runTests.sh -t 13 -p 8.2 -s composerUpdate

# Switch the working copy to the TYPO3 v14 dependency set.
Build/Scripts/runTests.sh -t 14 -p 8.2 -s composerUpdate

Note

Only composerUpdate installs the dependencies for the core version given with -t, composerInstall does not. To run a test suite against a specific TYPO3 core version, run composerUpdate -t <version> first and pass the same -t <version> to the suite afterwards. Suites executed with a different core version installed than selected report false positives. composerUpdate removes and reinstalls .Build/ and composer.lock (both git-ignored).

Run Build/Scripts/runTests.sh -h to see all options.

Running tests

# Unit tests.
Build/Scripts/runTests.sh -s unit

# Functional tests on SQLite (no database container required).
Build/Scripts/runTests.sh -s functional -d sqlite

# Functional tests against other database management systems.
Build/Scripts/runTests.sh -s functional -d mariadb -i 10.6
Build/Scripts/runTests.sh -s functional -d mysql -i 8.0
Build/Scripts/runTests.sh -s functional -d postgres -i 10

To run a single test class or method, append phpunit arguments after a -- separator (the wrapper parses its own options with getopts, so phpunit flags must follow --):

Build/Scripts/runTests.sh -s functional -d sqlite -- --filter EnvironmentBuilderFactoryTest

The functional Tests/Functional/Core13/ and Tests/Functional/Core14/ directories hold the TYPO3 core version specific tests, gated with phpunit groups (not-core-13 / not-core-14), so the wrapper automatically runs the set matching the installed core version.

Code quality

# Coding guidelines: fix in place ...
Build/Scripts/runTests.sh -s cgl

# ... or check only (no changes), as run in CI.
Build/Scripts/runTests.sh -s cgl -n

# Static analysis (PHPStan).
Build/Scripts/runTests.sh -s phpstan

# Render this documentation into Documentation-GENERATED-temp.
Build/Scripts/runTests.sh -s renderDocumentation

The documentation suite pulls ghcr.io/typo3-documentation/render-guides:latest before it renders, so a local run uses the renderer release that CI and docs.typo3.org use, and the summary names it in a Renderer: line. When the pull fails, for example because the registry cannot be reached, the suite renders with the cached image, says so and marks the summary line with (cached, pull failed). Without a cached image it fails. The renderer runs with --fail-on-log --fail-on-error, so a warning fails the suite as well. A new renderer release can therefore turn the suite red without a change in this repository.

Please make sure cgl -n, phpstan and the unit and functional test suites pass before opening a pull request.

Commit message rules

This repository follows the TYPO3 core commit message conventions.

Format

[TAG] Short imperative summary

A wrapped body (around 72 characters per line) that explains what the
change does and, more importantly, why it is needed. Describe the
behaviour change and the motivation, not the line-by-line diff.

Rules:

The subject line starts with a tag in square brackets, followed by a short summary in imperative mood ("Add", "Fix", "Rename"), capitalized and without a trailing period.
Keep the subject concise (aim for 52 characters, 72 at most).
Separate the subject from the body with a single blank line.
Wrap the body at around 72 characters and explain the what and why.
An issue reference is not required. When a change relates to a GitHub issue, you may reference it in the body (for example Resolves: #123).

Examples

[FEATURE] Add backend environment builder

[TASK] Mark concrete implementations as internal

[DOCS] Document the public API and stability guarantees

Tag	Use for
`[FEATURE]`	A new feature or capability.
`[TASK]`	Maintenance, refactoring, tooling, tests and other non-functional changes.
`[BUGFIX]`	A bug fix.
`[DOCS]`	Documentation-only changes.