From 3a23826dfdd046fa14b58149edc1696bfa23d066 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stefan=20B=C3=BCrk?= Date: Tue, 6 Oct 2026 11:23:46 +0200 Subject: [PATCH] [TASK] Add guidelines for contributors and agents CONTRIBUTING.md describes how a change gets into this branch: the supported versions, the test harness, the code rules, the commit messages and the pull requests. AGENTS.md adds what a coding agent needs on top of it, CLAUDE.md imports AGENTS.md. The three files are marked export-ignore, the agent working directory ".agent/" is ignored by git. --- .gitattributes | 3 + .gitignore | 1 + AGENTS.md | 93 ++++++++++++++++++++++ CLAUDE.md | 1 + CONTRIBUTING.md | 206 ++++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 304 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 CONTRIBUTING.md diff --git a/.gitattributes b/.gitattributes index d0c1999..2f73be3 100644 --- a/.gitattributes +++ b/.gitattributes @@ -15,6 +15,9 @@ .phplint.yml export-ignore .stylelintrc export-ignore docker-compose.yaml export-ignore +AGENTS.md export-ignore +CLAUDE.md export-ignore +CONTRIBUTING.md export-ignore # Enforce checkout with linux lf consistent over all plattforms *.xml text eol=lf diff --git a/.gitignore b/.gitignore index 11fb238..e6e1eeb 100644 --- a/.gitignore +++ b/.gitignore @@ -22,3 +22,4 @@ Build/node_modules/ vendor tailor-version-artefact/ tailor-version-upload/ +/.agent/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..5a33928 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,93 @@ +# Agent instructions + +Instructions for coding agents working in this repository. `CLAUDE.md` +imports this file. Read [CONTRIBUTING.md](CONTRIBUTING.md) first: its rules +apply to you in full. This file adds what an agent needs on top of it. + +## Know which line you are on + +This file belongs to the branch `main`: deepl-base 2.x, TYPO3 13.4 and 14.3, +PHP 8.2 to 8.5. **The branch you work on decides the rules.** For work on `1` +(1.x, TYPO3 12.4 and 13.4), switch to that branch and follow its own +`AGENTS.md` and `CONTRIBUTING.md`, never this one. A backport is written for +the target branch, it is not a copy of the change on `main`. + +Check before you start: + +```bash +git branch --show-current +git status -sb +``` + +## Rules + +- **Never write to a remote** (push, pull request, issue, comment, review, + merge) unless the maintainer asks for exactly that. +- **Never credit a tool or a model** in commits, pull requests, issues, code + comments or documentation. No `Co-authored-by` for it, no "Generated + with" line. The human who submits the change is its author. +- Scratch files, plans, reports and downloads go into `.agent/` (git + ignored), never into the tracked tree and never into `/tmp`. +- Verify by running, not by recalling: the suites below, `git`, `composer`. + Say what you ran and what you did not run. +- An issue reference (`DPL-123`, `#12`) is written only when it is known to + exist. Do not invent one. + +## Running the test harness as an agent + +- **Set `CI=true`.** Without a terminal, `runTests.sh` fails with "the input + device is not a TTY" unless `CI` is `true`: + + ```bash + export CI=true + Build/Scripts/runTests.sh -b docker -t 13 -s composerUpdate + Build/Scripts/runTests.sh -b docker -t 13 -s cgl -n + Build/Scripts/runTests.sh -b docker -t 13 -s phpstan + Build/Scripts/runTests.sh -b docker -t 13 -s unit + Build/Scripts/runTests.sh -b docker -t 13 -s functional + ``` + +- **One TYPO3 version at a time.** `.Build/` holds the installation of the + last `composerUpdate`. Run all suites of v13, then `composerUpdate -t 14` + and the suites of v14. Never run two `runTests.sh` calls of this checkout + in parallel. +- `composerUpdate` rewrites `composer.json` while it runs and restores it + afterwards (`composer.json.orig`). Do not interrupt it, and never commit a + `composer.json` changed by it. +- `-s cgl` changes files, `-s cgl -n` only checks. Run the check before you + commit, the fix only on purpose. +- Pass test filters behind `--`: `-s unit -- --filter LocalizationModeTest`. +- `-s buildCoreOverrideJavaScriptFiles` clones the whole TYPO3 repository + into `Build/buildsystem/` and builds its JavaScript. Run it only when a + TypeScript source in `Build/Overrides/` changed, and never edit the + compiled files in `Resources/Public/JavaScript/Core13/` by hand. +- Done means: the suites of the changed area green on **both** v13 and v14, + `cgl -n` and `phpstan` green on both, `renderDocumentation` when + `Documentation/` changed. + +## Code you are likely to touch + +- `Classes/` is loaded on both TYPO3 versions, `Core13/Classes/` on v13 only. + Code that only v13 needs goes into `Core13/`, never behind a version check + in a class. +- The localization modes, their events and the v13 wizard are deprecated + and removed in 3.0.0. Fix bugs there, do not extend them. +- deepltranslate-core, deepltranslate-glossary and deepl-write build on this + extension: the events in `Classes/Event/`, `LocalizationMode`, + `LocalizationModesCollection`, the listener identifiers `deepl-base/*` + they order themselves against, the `deeplbase:injectVariables` slots + (`languageTranslationDropdown`, `languageColumnButtons`) and + `DeeplBaseSvgIconProvider`. Changing them breaks those extensions. Say so + in the result and do not change them without being asked. +- The templates in `Resources/Private/Core13/Backend/` override templates of + TYPO3 itself (`Configuration/page.tsconfig`). Compare with the template of + the installed TYPO3 version before you change one. + +## Commits and pull requests + +- One commit per pull request, following the commit rules in CONTRIBUTING.md. + Amend and force push (`--force-with-lease`) when asked to update a pull + request, do not add fix-up commits. +- Rebase onto `origin/main`, never merge it in. +- When a change also needs a pull request in another DeepL extension, say so, + and name the order in which they have to be merged: this extension first. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..c2fe276 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,206 @@ +# Contributing to deepl-base + +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. + +deepl-base is the shared base of the DeepL extensions of web-vision. Its +documentation says it plainly: it is **not public API for other +extensions**. It follows semantic versioning as far as it can, but a minor +version may still break something. Keep that in mind before you build on it. + +## Table of contents + +- [Issues and security](#issues-and-security) +- [Branches](#branches) +- [What lives here](#what-lives-here) +- [Getting started](#getting-started) +- [Tests and checks](#tests-and-checks) +- [Code rules](#code-rules) +- [TYPO3 JavaScript overrides](#typo3-javascript-overrides) +- [Documentation and changelog](#documentation-and-changelog) +- [Commit messages](#commit-messages) +- [Pull requests](#pull-requests) +- [Other DeepL extensions](#other-deepl-extensions) + +## 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](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.4 | 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` and `bugfix/my-fix-1`), with 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, the structure and some code rules differ. + +## What lives here + +- **The localization wizard of the page module on TYPO3 v13**, replaced by + one whose modes come from events, so several extensions add their own + (`GetLocalizationModesEvent`, `LocalizationProcessPrepareDataHandlerCommandMapEvent`, + `LocalizationMode`, `LocalizationModesCollection`, the controller and the + listeners in `Core13/`). This part is **deprecated and removed in 3.0.0**. + TYPO3 v14 has its own localization handlers and does not need it. + Bug fixes are welcome, new features for it are not. +- **The translation dropdown of the page module on TYPO3 v13**, filled by + listeners of `ModifyInjectVariablesViewHelperEvent` through the + `deeplbase:injectVariables` ViewHelper and the template overrides in + `Resources/Private/Core13/Backend/`. +- **`DeeplBaseSvgIconProvider`**, a colour mode aware SVG icon provider for + all TYPO3 versions. + +## 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. + +```bash +git clone git@github.com:web-vision/deepl-base.git +cd deepl-base +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` | +| Unit tests | `Build/Scripts/runTests.sh -t 13 -s unit` | +| Unit tests, random order | `Build/Scripts/runTests.sh -t 13 -s unitRandom` | +| Functional tests | `Build/Scripts/runTests.sh -t 13 -s functional` | +| Functional tests, other DBMS | `... -s functional -d mariadb` (also `mysql`, `postgres`) | +| 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`. + +- Most of what this extension does only exists on TYPO3 v13. Its tests live + in `Tests/Functional/Core13/` and run with `-t 13`. +- 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` loads `Core13/Classes/` on TYPO3 v13 only. +- **No new TYPO3 version checks inside classes.** Code for TYPO3 v13 only + lives in `Core13/Classes/` (namespace `WebVision\Deepl\Base\Core13\`), + templates in `Resources/Private/Core13/`, JavaScript in + `Resources/Public/JavaScript/Core13/`. Configuration that differs is + selected by the major version in the configuration file itself + (`Configuration/JavaScriptModules.php`, `Configuration/Backend/AjaxRoutes.php`, + the `[typo3.branch == "13.4"]` condition in `Configuration/page.tsconfig`). + `DeeplBaseSvgIconProvider` still checks the version itself, do not add more + of that. +- Listener identifiers (`deepl-base/determine-default-typo3-localization-modes`, + `deepl-base/process-default-typo3-localization-modes`, + `deepl-base/default-translation`) are referenced by other extensions in + `after:`. Keep them. +- 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 PER-CS 1.0 (`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. + +## TYPO3 JavaScript overrides + +`Resources/Public/JavaScript/Core13/localization.js` and +`localization/provider-list.js` replace the modules of the same name of TYPO3 +v13 (`Configuration/JavaScriptModules.php`). They are **compiled**, never +edit them by hand: + +- The sources are TypeScript in `Build/Overrides/Core13/Sources/`, copies of + the TYPO3 sources with the changes of this extension. The `.orig-13.4.0` + file next to a source is the unchanged TYPO3 file, for comparing. +- `Build/Scripts/runTests.sh -t 13 -s buildCoreOverrideJavaScriptFiles` + clones TYPO3 into `Build/buildsystem/core13/` (git-ignored), checks out + `v13.4.0`, copies the sources in, builds them with the TYPO3 build and + copies the result back to `Resources/Public/JavaScript/Core13/`. It needs + network access and takes a while. +- Commit the changed source and the compiled result together. + +## 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 integrator notices + gets a changelog entry in `Documentation/Changelog//`, named + like the TYPO3 Core changelog: `Feature-.rst`, `Breaking-...`, + `Deprecation-...`, `Important-...`. It is part of the same commit. + +## Commit messages + +The [TYPO3 Core commit message rules](https://docs.typo3.org/m/typo3/guide-contributionworkflow/main/en-us/Appendix/CommitMessage.html): + +``` +[BUGFIX] DPL-240: Remove .Build/vendor before composer update + +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 `/`, for example + `bugfix/dpl-240-build-vendor`. + +## Other DeepL extensions + +deepltranslate-core and deepl-write use the localization modes and the +translation dropdown on TYPO3 v13, deepltranslate-core, -glossary and +deepl-write use the icon provider. A change to an event, a value object, a +listener identifier or the icon provider needs a matching change there. The +maintainers coordinate that: say in your pull request when you know a change +affects them.