Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
187 lines (152 loc) · 8.78 KB

CONTRIBUTING.md

File metadata and controls

187 lines (152 loc) · 8.78 KB
Raw

Contributing to deepl-write

Thank you for helping. This file explains how a change gets into this extension: which branch, how to test it, how to write the commit and what a pull request needs to be merged.

Table of contents

Issues and security

  • Bugs and feature requests are GitHub issues, with the templates offered when you open one. Include the TYPO3 version, the version of this extension and the steps to reproduce.
  • Security issues are never reported publicly. See SECURITY.md.
  • The maintainers track their work in an internal tracker, project DPL. That is why commits and pull requests refer to DPL-123. You do not need access to it.

Branches

Branch Version TYPO3 PHP State
main 2.x 13.4, 14.3 8.2 to 8.5 development of the next 2.x
1 1.x 12.4, 13.4 8.1 to 8.5 bug fixes and security fixes
  • Open a pull request against main. A fix that is needed in 1.x as well is a second pull request against 1, made after the first one, from a branch with the suffix -1 (bugfix/my-fix-main and bugfix/my-fix-1). Both carry the same title. The maintainers can do that second one for you.
  • The branch 1 has its own CONTRIBUTING.md. Read that one for a change there: the supported versions and some code rules differ.

Getting started

You need git, bash and docker or podman. Everything else runs in containers through Build/Scripts/runTests.sh, the same script the CI uses.

git clone git@github.com:web-vision/deepl-write.git
cd deepl-write
Build/Scripts/runTests.sh -h                        # all options and suites
Build/Scripts/runTests.sh -t 13 -s composerUpdate   # install for TYPO3 v13
Build/Scripts/runTests.sh -t 13 -s unit
  • -t selects the TYPO3 version (13, default, or 14). The installation in .Build/ exists once: run -s composerUpdate with the same -t before the suites of that version, and never two versions at the same time.
  • -b docker or -b podman selects the container binary. Without it, podman is used when it is installed.
  • -p selects the PHP version (default 8.2).

Tests and checks

A pull request is merged when these are green for TYPO3 v13 and v14. Run them locally before you push:

Check Command
Coding style (check only) Build/Scripts/runTests.sh -t 13 -s cgl -n
Coding style (fix) Build/Scripts/runTests.sh -t 13 -s cgl
PHPStan Build/Scripts/runTests.sh -t 13 -s phpstan
PHP lint Build/Scripts/runTests.sh -t 13 -s lintPhp
TypoScript lint Build/Scripts/runTests.sh -t 13 -s lintTypoScript
Unit tests Build/Scripts/runTests.sh -t 13 -s unit
Functional tests Build/Scripts/runTests.sh -t 13 -s functional
Functional tests, other DBMS ... -s functional -d mariadb (also mysql, postgres)
Bundled library in sync Build/Scripts/runTests.sh -t 13 -s checkContribComposer
Exception codes unique Build/Scripts/runTests.sh -s checkExceptionCodes
Test method names Build/Scripts/runTests.sh -s checkTestMethodsPrefix
UTF-8 without BOM Build/Scripts/runTests.sh -s checkBom
Documentation renders Build/Scripts/runTests.sh -s renderDocumentation

The same with -t 14 after -s composerUpdate -t 14. CI runs checkContribComposer with TYPO3 v13 only.

  • The functional tests talk to a DeepL mock server container, not to DeepL. They need no API key and cost nothing.
  • A bug fix comes with a test that fails without it. A new feature comes with tests.

Code rules

  • declare(strict_types=1); in every PHP file, classes final unless they are meant to be extended, dependencies as readonly promoted constructor properties.
  • Services are stateless. They carry no data from one call to the next.
  • Dependency injection through Symfony attributes (#[AsEventListener], #[Autoconfigure], ...). Services.yaml keeps the defaults and the resource. Services.php only loads the directory of the running TYPO3 version.
  • No TYPO3 version checks inside classes. Code that differs between v13 and v14 lives in Core13/ and Core14/ (namespaces WebVision\DeeplWrite\Core13\ and WebVision\DeeplWrite\Core14\). Configuration/Services.php loads only the directory of the running version. A new difference goes there, not into a Typo3Version check.
  • Every exception gets a unique code, the Unix timestamp of the moment you write it.
  • Test methods use the #[Test] attribute and do not start with test.
  • Coding style is PSR-2 with the PHP 7.4 migration rules (Build/php-cs-fixer/php-cs-rules.php). PHPStan runs on level 8 with a baseline per TYPO3 version in Build/phpstan/. A change does not add to the baselines.

The bundled library for classic mode

The readability score uses org_heigl/hyphenator. Composer installations get it from composer.json. For classic mode (TER) installations the release workflow installs it into contrib/Libraries/ from contrib/composer.json and contrib/composer.lock. contrib/Libraries/ is not committed.

  • The constraint of org_heigl/hyphenator in composer.json and contrib/composer.json must be identical.
  • contrib/composer.lock is resolved with --prefer-lowest, so the lowest supported version is the one shipped. After a change to contrib/composer.json, regenerate it with composer update --prefer-lowest -d contrib.
  • -s checkContribComposer checks both.

Documentation and changelog

  • The documentation is reStructuredText in Documentation/, rendered with -s renderDocumentation. The rendered result is not committed.
  • A feature, a breaking change, a deprecation or a fix an editor or integrator notices gets a changelog entry in Documentation/Changelog/<major.minor>/, named like the TYPO3 Core changelog: Feature-<Topic>.rst, Breaking-..., Deprecation-..., Important-.... It is part of the same commit.

Commit messages

The TYPO3 Core commit message rules:

[BUGFIX] DPL-237: Correct the branch alias

Explain why the change is needed and what it does, not how the diff
looks. Wrap the body at 72 characters.
  • Subject: a tag ([FEATURE], [BUGFIX], [TASK], [DOCS], [SECURITY], [!!!] in front for a breaking change), the internal issue if there is one, imperative mood, at most 52 characters where possible.
  • A GitHub issue goes into the footer (Resolves: #12) or at the end of the subject ((#12)).

Pull requests

  • One pull request carries one commit. The title of the pull request is the subject of the commit. Review changes are amended into the commit and force pushed, not added as new commits.
  • Rebase onto the current main instead of merging it in. The branch is merged with "rebase and merge", the only method allowed.
  • Required: one approving review and the checks code quality with core v13 (8.2), all tests with core v13 (8.2), all tests with core v13 (8.5), the same for v14, and render documentation.
  • Name the branch <type>/<topic>, for example bugfix/dpl-237-branch-alias-main or task/security-policy.

Other DeepL extensions

deepl-write builds on web-vision/deepl-base and web-vision/deeplcom-deepl-php (the DeepL PHP SDK). It does not need web-vision/deepltranslate-core, but works together with it when both are installed:

  • Without an API key of its own, deepl-write uses the key of deepltranslate-core.
  • In the site configuration, the DeepL Write language and the target language and formality of deepltranslate-core exclude each other.
  • On TYPO3 v13 its entry in the translation dropdown of the page module is ordered after the one of deepltranslate-core.

A change to these places, or to the events of deepl-base it listens to, is checked with deepltranslate-core installed as well. Say in your pull request when you know a change affects another DeepL extension.