Contribution 

Contributions are essential to the success of open source projects, but they are by no means limited to contributing code. Much more can be done, for example by improving the documentation or answering questions on stackoverflow.com.

Contribution workflow 

  1. Please always create an issue on Github before starting a change. This is very helpful to understand what kind of problem the pull request solves, and whether your change will be accepted.
  2. Bug fixes: Please describe the nature of the bug you wish to report and provide how to reproduce the problem. We will only accept bug fixes if we can can reproduce the problem.
  3. Features: Not every feature is relevant to the majority of users. In addition: We do not want to complicate the usability of this extension for a marginal feature. It helps to have a discussion about a new feature before before opening a pull request.
  4. Please always create a pull request based on the updated release branch. This ensures that the necessary quality checks and tests are performed as a quality can be performed.

Contribution information 

Commit message 

  • This repository uses similar subject prefixes like convential commits, but follows the known prefixes used in the TYPO3 Community:

    • [FEATURE] instead of feat: for changes introducing new features. Requires a Feature-*.rst changelog file.
    • [BUGFIX] instead of fix:
    • [TASK] instead of chore: for any task.
    • [DOCS] instead of docs: for documentation or markdown file related changes.
    • [!!!] before the other prefixes instead of ! or BREAKING to hint breaking changes. Requires a Breaking-*.rst changelog file.

    with special [!!!] before task or feature indicating breaking changes.

Documentation and Changelog 

  • Breaking changes indicated with prefix [!!!] requires a Breaking-*.rst changelog file.
  • Features indicated with prefix [FEATURE] requires a Feature-*.rst changelog file.
  • Tasks deprecation methods, classes or functionality needs to be documented adding Deprecation-*.rst changelog files.
  • In case important information needs to be documented Important-*.rst changelog files could be provided.

Documentation is rendered locally using:

Build/Scripts/runTests.sh -s renderDocumentation
Copied!

and can ge viewed in the browser opening Documentation-GENERATED-temp/Index.html for example on linux with:

xdg-open Documentation-GENERATED-temp/Index.html
Copied!

Executing toolchain 

All related development tools are executed using the Build/Scripts/runTests.sh command dispatcher.

Available general options:

  • -b <docker|podman> allows to set the container system to use in case both are available, otherwise it is determined. podman is used over docker if not enforced using this option.
  • -s <suite> selectes the suite (command) to execute, see -h for full description of available options and suites.
  • -p <8.2|8.2|8.3|8.4|8.5> defines the PHP version to use for PHP related suites and commands, for example phpunit, phpstan or composer operations.
  • -x enforces xdebug profile=debug for php script executions, use-ful to debug unit- or functional tests.
  • -d <sqlite|mysql|mariadb|postgres> selects the database to use for functional tests and starts/stops/cleans the selected container.
  • -i <version> allows to select the database server version for MariaDB, MySQL or PostgreSQL. See -h for the list of available options. Used for functional tests.

Examples 

functional tests for TYPO3 v13.4 with PHP 8.2 
Build/Scripts/runTests.sh -t 13 -p 8.2 -s composerUpdate && \
Build/Scripts/runTests.sh -t 13 -p 8.2 -s functional -d sqlite && \
Build/Scripts/runTests.sh -t 13 -p 8.2 -s functional -d mariadb -i 10.7
Copied!
functional test for TYPO3 v14.3 with PHP 8.5 
Build/Scripts/runTests.sh -t 14 -p 8.5 -s composerUpdate && \
Build/Scripts/runTests.sh -t 14 -p 8.5 -s functional -d sqlite && \
Build/Scripts/runTests.sh -t 14 -p 8.5 -s functional -d mariadb -i 10.7
Copied!

Functional tests in the PHPUnit group deepl-real-api send content to the real DeepL API instead of the mock server. Every run is billed per character, so the functional suite and CI exclude them. Run them locally with your own API key in the environment variable DEEPL_AUTH_KEY. Read the key with read -rs, it is neither shown nor written to the shell history, which a key typed into the command line would be:

functional tests against the real DeepL API 
read -rs DEEPL_AUTH_KEY && export DEEPL_AUTH_KEY
Build/Scripts/runTests.sh -t 13 -p 8.2 -s functionalDeepLApi
unset DEEPL_AUTH_KEY
Copied!

A failing test shows the translation and the raw answer of DeepL. To keep the request text, the answer and the billed characters of every call, name a file below the extension directory in DEEPL_REAL_API_LOG. The API key is never written to it. The key is read the same way:

functional tests against the real DeepL API, with a log of every call 
read -rs DEEPL_AUTH_KEY && export DEEPL_AUTH_KEY
CI_PARAMS="-e DEEPL_REAL_API_LOG=$PWD/.Build/deepl-real-api.jsonl" \
    Build/Scripts/runTests.sh -t 13 -p 8.2 -s functionalDeepLApi
unset DEEPL_AUTH_KEY
Copied!
unit tests for TYPO3 v13.4 with PHP 8.5 
Build/Scripts/runTests.sh -t 13 -p 8.5 -s composerUpdate && \
Build/Scripts/runTests.sh -t 13 -p 8.5 -s unit && \
Build/Scripts/runTests.sh -t 13 -p 8.5 -s unitRandom
Copied!
unit tests for TYPO3 v14.3 with PHP 8.2 
Build/Scripts/runTests.sh -t 14 -p 8.2 -s composerUpdate && \
Build/Scripts/runTests.sh -t 14 -p 8.2 -s unit && \
Build/Scripts/runTests.sh -t 14 -p 8.2 -s unitRandom
Copied!
Code style fixer 
Build/Scripts/runTests.sh -t 13 -p 8.2 -s composerUpdate && \
Build/Scripts/runTests.sh -t 13 -p 8.2 -s cgl
Copied!
Static code analyzer - analyze 
Build/Scripts/runTests.sh -t 13 -p 8.2 -s composerUpdate && \
Build/Scripts/runTests.sh -t 13 -p 8.2 -s phpstan && \
Build/Scripts/runTests.sh -t 14 -p 8.2 -s composerUpdate && \
Build/Scripts/runTests.sh -t 14 -p 8.2 -s phpstan
Copied!
Static code analyzer - regenerate PHPStan baseline 
Build/Scripts/runTests.sh -t 13 -p 8.2 -s composerUpdate && \
Build/Scripts/runTests.sh -t 13 -p 8.2 -s phpstanGenerateBaseline && \
Build/Scripts/runTests.sh -t 14 -p 8.2 -s composerUpdate && \
Build/Scripts/runTests.sh -t 14 -p 8.2 -s phpstanGenerateBaseline
Copied!