[TASK] Add guidelines for contributors and agents

.gitattributes

@@ -8,6 +8,9 @@
 /packages/ export-ignore
 
 # Files
+AGENTS.md export-ignore
+CLAUDE.md export-ignore
+CONTRIBUTING.md export-ignore
 .editorconfig export-ignore
 .gitattributes export-ignore
 .gitignore export-ignore

.gitignore

@@ -21,3 +21,4 @@ Build/node_modules/
 vendor
 tailor-version-artefact/
 tailor-version-upload/
+/.agent/

AGENTS.md

@@ -0,0 +1,92 @@
+# 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 `1`: deepl-write 1.x, TYPO3 12.4 and 13.4,
+PHP 8.1 to 8.5, bug fixes and security fixes only. **The branch you work on
+decides the rules.** For work on `main` (2.x), switch to it and follow its
+own `AGENTS.md`.
+
+Check before you start:
+
+```bash
+git branch --show-current     # must print 1
+git status -sb
+```
+
+## Backports
+
+Most work on this branch is a backport of a fix made on `main`. The code of
+`main` does not fit here as it is:
+
+- `main` puts version differences into `Core13/` and `Core14/`. This branch
+  has neither, and does not get them: a difference between v12 and v13 is a
+  `Typo3Version` check at the place, as the branch already does.
+- `main` registers event listeners with `#[AsEventListener]`. Here they are
+  tagged in `Configuration/Services.yaml`, TYPO3 v12 has no such attribute.
+- `main` requires PHP 8.2 and deepl-base 2.x. Here the floor is PHP 8.1 and
+  deepl-base 1.x: no `readonly` classes, no DNF types, no typed class
+  constants, no `#[\Override]`, no deepl-base 2.x or TYPO3 v14 API.
+- `main` has the readability score, `org_heigl/hyphenator` and `contrib/`.
+  This branch has none of them. A change to those is not backported.
+- `main` adds a changelog entry in `Documentation/Changelog/`. This branch
+  has none, do not create it.
+
+Port the behaviour, keep the commit subject and body of `main` and adapt the
+body where the change differs. Cherry-pick when it applies cleanly, then
+check every hunk against the list above. Say in the result what had to be
+adapted.
+
+## 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. 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. 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.
+
+## 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 12 -p 8.1 -s composerUpdate
+  Build/Scripts/runTests.sh -b docker -t 12 -p 8.1 -s cgl -n
+  Build/Scripts/runTests.sh -b docker -t 12 -p 8.1 -s phpstan
+  Build/Scripts/runTests.sh -b docker -t 12 -p 8.1 -s unit
+  Build/Scripts/runTests.sh -b docker -t 12 -p 8.1 -s functional
+  ```
+
+  Then the same with `-t 13 -p 8.2`, starting with `composerUpdate`.
+- **One TYPO3 version at a time.** `.Build/` holds the installation of the
+  last `composerUpdate`. Never run two `runTests.sh` calls of this checkout in
+  parallel.
+- `composerUpdate` rewrites `composer.json` while it runs and restores it
+  afterwards. Do not interrupt it, never commit a `composer.json` changed by
+  it.
+- `-s cgl` changes files, `-s cgl -n` only checks.
+- The CI of this branch does not run PHPStan and the tests. Run them for the
+  code you change and report their result, also when they fail for reasons
+  outside your change. Do not claim a green CI covers them.
+- The functional tests use a DeepL mock server. Never put a real DeepL key
+  into a file, a command line or a log.
+- Done means: `cgl -n` green on v12 (PHP 8.1) and v13, and the result of
+  PHPStan and the tests of the changed area stated for both.
+
+## Commits and pull requests
+
+- One commit per pull request, branch name ending in `-1`, the same title as
+  on `main`. Amend and force push (`--force-with-lease`) when asked to update
+  it.
+- Rebase onto `origin/1`, never merge it in.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

CONTRIBUTING.md

@@ -0,0 +1,144 @@
+# Contributing to deepl-write 1.x
+
+This is the branch `1`: deepl-write 1.x for TYPO3 12.4 and 13.4. It receives
+bug fixes and security fixes. New features are developed on `main` (2.x),
+whose `CONTRIBUTING.md` describes the extension as it is developed today.
+This file describes the rules of this branch.
+
+## Table of contents
+
+- [Issues and security](#issues-and-security)
+- [Branches](#branches)
+- [Getting started](#getting-started)
+- [Tests and checks](#tests-and-checks)
+- [Code rules on this branch](#code-rules-on-this-branch)
+- [Documentation](#documentation)
+- [Commit messages](#commit-messages)
+- [Pull requests](#pull-requests)
+
+## Issues and security
+
+- Bugs are GitHub issues, with the templates offered when you open one. Say
+  that you use 1.x, and which TYPO3 version.
+- **Security issues are never reported publicly.** See
+  [SECURITY.md](SECURITY.md). 1.x receives security fixes until the date
+  named there.
+- The maintainers track their work in an internal tracker, project `DPL`.
+  That is why commits 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                   |
+| `1`    | 1.x     | 12.4, 13.4   | 8.1 to 8.5 | bug fixes and security fixes  |
+
+- A fix is made on `main` first, when `main` has the bug too, and then
+  brought to this branch in a second pull request. Name its branch after the
+  one of `main` with the suffix `-1` (`bugfix/my-fix-1`). It carries the same
+  title as the pull request on `main`.
+- A fix that only concerns 1.x is a pull request against `1` directly.
+- **A backport is written for this branch.** The code of `main` uses APIs,
+  PHP features and a structure that 1.x does not have. Adapt the change to
+  the rules below, do not copy it.
+
+## 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-write.git
+cd deepl-write
+git switch 1
+Build/Scripts/runTests.sh -h                        # all options and suites
+Build/Scripts/runTests.sh -t 12 -s composerUpdate   # install for TYPO3 v12
+Build/Scripts/runTests.sh -t 12 -s unit
+```
+
+- `-t` selects the TYPO3 version (`12`, default, or `13`). 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.
+- `-p` selects the PHP version (default 8.2). TYPO3 v12 is checked on PHP 8.1
+  in CI: run v12 with `-p 8.1` to catch syntax 8.1 does not know.
+- `-b docker` or `-b podman` selects the container binary. Without it,
+  podman is used when it is installed.
+
+## Tests and checks
+
+The CI of this branch runs the code quality checks only: `composerUpdate`,
+`lintTypoScript`, `lintPhp`, `cgl -n`, `checkTestMethodsPrefix`, `checkBom`
+and `checkExceptionCodes`, for TYPO3 v12 on PHP 8.1 and v13 on PHP 8.2.
+PHPStan and the test suites are disabled in its workflows. Run them locally
+anyway for the code you change:
+
+| Check                         | Command                                                  |
+|-------------------------------|----------------------------------------------------------|
+| Coding style (check only)     | `Build/Scripts/runTests.sh -t 12 -p 8.1 -s cgl -n`       |
+| PHP lint                      | `Build/Scripts/runTests.sh -t 12 -p 8.1 -s lintPhp`      |
+| TypoScript lint               | `Build/Scripts/runTests.sh -t 12 -p 8.1 -s lintTypoScript` |
+| Exception codes unique        | `Build/Scripts/runTests.sh -s checkExceptionCodes`       |
+| PHPStan (not in CI)           | `Build/Scripts/runTests.sh -t 12 -p 8.1 -s phpstan`      |
+| Unit tests (not in CI)        | `Build/Scripts/runTests.sh -t 12 -p 8.1 -s unit`         |
+| Functional tests (not in CI)  | `Build/Scripts/runTests.sh -t 12 -p 8.1 -s functional`   |
+
+The same with `-t 13 -p 8.2` after `-s composerUpdate -t 13 -p 8.2`.
+
+- The functional tests talk to a DeepL mock server container, not to DeepL.
+- A bug fix comes with a test that fails without it, where the area has
+  tests.
+
+## Code rules on this branch
+
+The rules of `main` apply where TYPO3 v12 and PHP 8.1 allow them. These are
+the differences:
+
+- **PHP 8.1.** No `readonly` classes, no disjunctive normal form types, no
+  typed class constants, no `#[\Override]`. `readonly` promoted properties
+  are fine.
+- **Event listeners are registered in `Configuration/Services.yaml`** with
+  the tag `event.listener`. TYPO3 v12 does not know `#[AsEventListener]`.
+  Services that have to be public are declared there as well.
+- **No `Core12/` or `Core13/` directories.** Where v12 and v13 differ, this
+  branch checks the version at that place (`Typo3Version`). Keep such places
+  few, and do not restructure the branch in a fix.
+- No API of TYPO3 v14 and nothing that needs deepl-base 2.x: this branch
+  uses deepl-base 1.x. The localization wizard modes come from its events
+  on both TYPO3 versions.
+- 1.x has no readability score, no `org_heigl/hyphenator` and no `contrib/`
+  directory. Changes of `main` to those do not apply here.
+- 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/Core12` and `Core13`. A change
+  does not add to the baselines.
+- Every exception gets a unique code, the Unix timestamp of the moment you
+  write it. Tests use the `#[Test]` attribute.
+
+## Documentation
+
+The documentation in `Documentation/` describes 1.x. Change it when a fix
+changes what it describes. This branch has no `Documentation/Changelog/`: a
+fix needs no changelog entry.
+
+## Commit messages
+
+The [TYPO3 Core commit message rules](https://docs.typo3.org/m/typo3/guide-contributionworkflow/main/en-us/Appendix/CommitMessage.html),
+the same as on `main`:
+
+```
+[BUGFIX] DPL-237: Correct the branch alias
+
+Explain why the change is needed and what it does. Wrap the body at 72
+characters.
+```
+
+A backport keeps the subject and the body of the commit on `main` and adapts
+the body where the 1.x change differs.
+
+## Pull requests
+
+- One pull request carries one commit, its title the subject of the commit.
+  Review changes are amended and force pushed.
+- Rebase onto the current `1`. The branch is merged with "rebase and merge".
+- Required: one approving review and the checks `code quality with core v12
+  (8.1)` and `code quality with core v13 (8.2)`.