From 1bcaf98a4495f526aef69dc79871754e743512c0 Mon Sep 17 00:00:00 2001 From: Lina Wolf <> Date: Tue, 8 Sep 2026 20:26:22 +0200 Subject: [PATCH] [TASK] Add AGENTS.md with repository-specific agent instructions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AI coding agents working in this repository have no way to know where the manual lives, how to render and validate it, or which writing conventions apply — so they guess, and guess wrong. AGENTS.md records that once: the repository layout, the make targets and pre-commit hooks, the reST style rules from the How to Document guide, and the commit message and pull request conventions used here. CLAUDE.md just imports AGENTS.md, so Claude Code reads the same file rather than a second copy that drifts out of sync. Releases: main, 14.3, 13.4 Assisted-by: Claude Opus 5 Signed-off-by: Lina Wolf --- AGENTS.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 94 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..ccd6a27 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,93 @@ +# AGENTS.md — Frontend Localization Guide + +## Repo structure + +``` +Documentation/ # the actual manual (reST source, published to docs.typo3.org) +CONTRIBUTING.md # how to contribute +``` + +## Commands + +- `make docs` — render the manual locally with Docker +- `make test-docs` — render in fail-on-log mode; use this to validate any change before committing +- `pre-commit run --all-files` — apply the whitespace hooks + (`trailing-whitespace`, `end-of-file-fixer`) configured in + `.pre-commit-config.yaml`; `pre-commit install` wires them into `git commit` + +## Scope + +This manual covers making a TYPO3 *website* multilingual: site languages, +page and content translation, language menus, localized labels and character +sets. Its audience is integrators building a translated frontend. + +Do not confuse it with the +[Localization Team Guidelines](https://github.com/TYPO3-Documentation/localization-team-guidelines), +which is about the process of translating TYPO3 itself on Crowdin. + +Language handling changed substantially across TYPO3 versions, so verify +site configuration keys, TypoScript properties and fallback behaviour +against the Core source of the version being documented rather than from +memory. + +## Documentation writing rules + +Follow the official TYPO3 documentation writing conventions (see +https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument): + +1. **reST, not Markdown** — everything under `Documentation/` is reStructuredText. +2. **Sentence case headlines** — first word and proper nouns only: + https://docs.typo3.org/permalink/h2document:content-styleguide-title-capitalization +3. **4-space indentation** for directive bodies, 2 spaces after `..` markers: + https://docs.typo3.org/permalink/h2document:cgl-indenting +4. **Single backticks over double**, unless the content needs a literal + backtick: https://docs.typo3.org/permalink/h2document:inline-code +5. **Every headline needs a `.. _anchor:` target** directly above it + (https://docs.typo3.org/permalink/h2document:link-anchor), and anchors are + never removed once published + (https://docs.typo3.org/permalink/h2document:anchor-persistence). +6. **Validate before committing** — run `make test-docs`, and run the + pre-commit hooks (see Commands). +7. **Never commit or push without being asked.** + +## Commit message format + +Follow https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Howto/EditLocal.html: + +- Prefix the subject line with `[TASK]`, `[BUGFIX]`, or `[FEATURE]`, + followed by a short, imperative summary. +- Explain *why* the change is needed in the body — the diff already shows + what changed. +- End with a `Signed-off-by: Your Name ` trailer. +- If AI assistance went beyond basic spelling/grammar checks, add an + `Assisted-by: ` trailer, e.g. + `Assisted-by: Claude Sonnet 5 `. +- If the change should be backported, add a `Releases: main, 14.3, 13.4` + trailer listing every branch it applies to. This repo maintains multiple + LTS branches, so `Releases:` applies here — including for changes to + these agent instruction files themselves, since agents may be working + on an older branch where a change is still relevant. + +## Pull requests + +- When a commit is the only commit in the PR, the PR title and body must + match the commit's subject and body exactly. +- When the commit message has a `Releases:` trailer naming branches beyond + `main`, attach the matching `backport ` label (e.g. + `backport 14.3`, `backport 13.4`) to the PR for each of those branches + when opening it — don't wait to be asked. +- Adding labels requires triage/write access, which an external + contributor's account (e.g. a fork-based PR) usually doesn't have. If + attaching a label fails for that reason, don't treat it as an error and + don't note the failure in the PR — just skip it silently. + +## For maintainers + +- A PR opened by an agent may be missing its `backport ` labels + if the agent's account lacked permission to add them. Check for and add + any missing backport labels yourself before/when merging such a PR. + +## References + +- [TYPO3CMS-Guide-HowToDocument](https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument) — official writing style guide and reST reference +- https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Howto/EditLocal.html — commit/PR conventions 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