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 v12 on PHP 8.2 (default matrix).
Build/Scripts/runTests.sh -t 12 -p 8.2 -s composerUpdate

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

Note

The -t option only influences what composerInstall / composerUpdate installs. To run the test suites against TYPO3 v13 you must run composerUpdate -t 13 first; afterwards pass -t 13 to the suite as well. 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/Core12/ and Tests/Functional/Core13/ directories are gated with phpunit groups (not-core-12 / not-core-13), 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

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 and other non-functional changes.
`[BUGFIX]`	A bug fix.
`[DOCS]`	Documentation-only changes.
`[TEST]`	Changes to tests only.