|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +## Rules |
| 4 | + |
| 5 | +* No persistent agent memory for this project. Source of truth: this |
| 6 | + file, the checkout, the git history. Durable knowledge → PR against |
| 7 | + this file. |
| 8 | +* **Never** write package or version facts into this file — no TYPO3/PHP |
| 9 | + versions, no branch versions, no matrix. They are read from the branch |
| 10 | + you are on: `composer.json`, `.github/workflows/ci.yml`, |
| 11 | + `Build/.nvmrc`, `.ddev/config.yaml`. A change has to hold on every |
| 12 | + TYPO3 major that branch declares, not just the installed one. |
| 13 | +* Don't guess TYPO3 APIs, TCA keys, icons, labels — read |
| 14 | + `.build/vendor/typo3/`. |
| 15 | +* Only report checks you actually ran. |
| 16 | +* Everything that only serves development is `export-ignore`d in |
| 17 | + `.gitattributes` — this file included; it never ships in the package |
| 18 | + artifact. |
| 19 | + |
| 20 | +## Style |
| 21 | + |
| 22 | +* Short, tight, precise — in code, comments, commit messages, PRs and |
| 23 | + docs alike |
| 24 | +* Comments say why, never what the code already says; no captain |
| 25 | + obvious, no restated signatures, no block comment where a good name |
| 26 | + does the job |
| 27 | +* No over-explained code and no ceremony; a stale comment gets deleted, |
| 28 | + not updated |
| 29 | +* Describe what is, never what was — no history, no "previously", no |
| 30 | + "changed from", no former behaviour in code, comments or docs |
| 31 | +* Match the surrounding code: naming, structure, comment density |
| 32 | +* Wrap Markdown and reST at 72 characters |
| 33 | + |
| 34 | +## Commands |
| 35 | + |
| 36 | +* `ddev start` · `ddev launch typo3` · `ddev composer …` (provides the |
| 37 | + DB for functional tests) |
| 38 | +* `composer test` — lint + unit + functional; functional needs the DB → |
| 39 | + `ddev composer test:php:functional` |
| 40 | +* `composer cgl:ci` (check) · `composer cgl` (rewrites) |
| 41 | +* `composer phpstan` — `Build/phpstan.neon` |
| 42 | +* `composer changelog` · `composer set-version` |
| 43 | +* `npm --prefix Build ci && npm --prefix Build run build` — full asset |
| 44 | + build |
| 45 | +* PHPStan baselines are split per TYPO3 major |
| 46 | + (`Build/phpstan-baseline-*.neon`); `composer phpstan:baseline` writes |
| 47 | + elsewhere — move the entries, prefer fixing |
| 48 | + |
| 49 | +## Tests |
| 50 | + |
| 51 | +* `Tests/Unit` and `Tests/Functional`; functional tests boot the fixture |
| 52 | + package `Tests/Packages/demo_package` |
| 53 | +* A bugfix you write comes with a test that fails without it — that is |
| 54 | + the proof. Skip it only when it cannot be tested, and say so in the PR |
| 55 | +* For human contributors the same test is a wish, not a requirement — |
| 56 | + never reject a pull request over it |
| 57 | + |
| 58 | +## Frontend build |
| 59 | + |
| 60 | +* Sources: `Build/`, `Resources/Public/Scss/` |
| 61 | +* Build output is committed: |
| 62 | + `Resources/Public/Css|JavaScript|Fonts|Icons` |
| 63 | +* SCSS/JS/icon change → rebuild, commit generated files in the same |
| 64 | + commit; CI job `build-frontend` fails on a dirty tree |
| 65 | +* Node lives in `Build/.nvmrc` and `Build/package.json`; keep |
| 66 | + `nodejs_version` in `.ddev/config.yaml` and the CI setup on it |
| 67 | + |
| 68 | +## Branches |
| 69 | + |
| 70 | +* Work always happens on a topic branch, ideally in its own git |
| 71 | + worktree — never directly in the shared checkout, and never on |
| 72 | + `master` or a release branch |
| 73 | +* Topic branches are named after what they do, prefixed by type: |
| 74 | + `task/…`, `bugfix/…`, `feature/…` — e.g. |
| 75 | + `bugfix/indexed-search-pagination` |
| 76 | +* Every change goes to `master` first, always as a pull request, never |
| 77 | + as a direct push |
| 78 | +* Once it is merged, backport it: cherry-pick onto the release branches |
| 79 | + it affects, one pull request per branch — check whether it applies |
| 80 | + there, declared versions and tooling differ per branch |
| 81 | +* Release branches are named `BP_<major>_<minor>` |
| 82 | + |
| 83 | +## Commits and PRs |
| 84 | + |
| 85 | +* PRs are always squash-merged into `[TYPE] Subject (#<PR number>)`, |
| 86 | + e.g. `[TASK] Drop empty ext_tables.php files (#1641)` |
| 87 | +* Types: `[BUGFIX]`, `[TASK]`, `[FEATURE]`; no issue number in the |
| 88 | + subject |
| 89 | +* Don't squash a PR branch yourself — the merge does it, original |
| 90 | + commits keep attribution |
| 91 | +* Every commit carries a `Signed-off-by:` trailer with the contributor's |
| 92 | + name and mail from `git config` — commit with `git commit -s` |
| 93 | + |
| 94 | +## Agent attribution |
| 95 | + |
| 96 | +* Agent involvement belongs in the PR's *AI assistance* section, and |
| 97 | + nowhere else. Fill it in fully and honestly: agent and version, model |
| 98 | + and effort level, share written by the agent, human review |
| 99 | +* Never expose agent sessions: no session links, no tool footers, no |
| 100 | + "generated with …" lines in commit messages, PR titles or PR bodies |
| 101 | +* Never add an agent as author or `Co-Authored-By` — commits and pull |
| 102 | + requests carry the human contributor only |
| 103 | + |
| 104 | +## Worktrees |
| 105 | + |
| 106 | +* Never move a branch ref (`git branch -f master <commit>`) — the |
| 107 | + checkout holding that branch stays behind and shows the whole delta as |
| 108 | + staged changes |
| 109 | +* Commit in the worktree, push a topic branch, open a PR; check |
| 110 | + `git worktree list` before touching any ref |
| 111 | + |
| 112 | +## Documentation |
| 113 | + |
| 114 | +* User-facing changes → `Documentation/` (reST); `CHANGELOG.md` is |
| 115 | + generated |
| 116 | +* Human contribution notes: `Documentation/Contribution/Index.rst` — |
| 117 | + keep in sync with this file |
0 commit comments