From c6663b561a628610f84696488756e68e7fbba6b4 Mon Sep 17 00:00:00 2001 From: Oto Macenauer Date: Fri, 14 Aug 2026 12:25:34 +0200 Subject: [PATCH] docs: add AGENTS.md contributor and agent checklist MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Collects what CI actually enforces on a pull request — branch pattern, conventional title, description minimum, issue reference, 50-file cap — in one place, alongside the repository conventions a change is expected to respect (hermetic builds, light-only, untrusted sub-app input, portability, contract stability, SHA-pinned actions). Calls out explicitly that the branch prefixes and the commit/PR title types are different sets: `perf` and `refactor` are valid titles but invalid branch prefixes, which is the easiest way to get a red PR on otherwise correct work. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01QqFK6yffibtCBTF8xZ4hXW --- AGENTS.md | 149 ++++++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 5 ++ 2 files changed, 154 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d348e63 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,149 @@ +# AGENTS.md + +Working agreement for automated agents and contributors making changes in this +repository. It exists so a change lands green on the first CI run instead of the +third. + +Read [`CLAUDE.md`](CLAUDE.md) for the architecture and [`CONTRIBUTING.md`](CONTRIBUTING.md) +for the human-facing summary. This file is the mechanical checklist. + +## Non-negotiables + +CI enforces every rule in this section. `.github/workflows/pr-requirements.yml` +runs `AbsaOSS/check-pr-requirements` on every PR event, so a PR that violates a +rule is red before any code is looked at. + +### Branch name + +``` +^(feat|feature|fix|bugfix|hotfix|release|support|chore|docs|ci|test|dependabot)/[a-zA-Z0-9._/-]+$ +``` + +Branch off `master`. `master` is the only allowed target branch. + +Examples: `fix/build-pipeline-hardening`, `docs/agents-guide`, `chore/asset-copy`. + +> **The branch prefixes are not the same set as the commit/PR title types.** +> `perf`, `refactor`, `style`, `build` and `revert` are valid *title* types but +> **invalid branch prefixes** — a `perf/…` branch fails the check. Use `chore/…` +> (or `fix/…`) for that work and keep the `perf:` prefix in the title. + +### PR title — Conventional Commits + +``` +: +``` + +Allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, +`build`, `ci`, `chore`, `revert`. A scope is optional (`fix(build): …`). + +### PR description + +- **At least 20 characters.** A one-word body fails. +- **Must reference an issue.** Use a closing keyword so the issue is resolved on + merge: `Closes #42`. Reference every issue an aggregated PR resolves, each on + its own line. + +Template that satisfies the checker: + +```markdown +## What + +One paragraph on what changed and why. + +## Changes + +- `path/to/file.js` — what and why + +## Verification + +- `npm run build:headless` — green +- `npm test` — green +- `npx playwright test --config=playwright.config.ci.js` — green + +Closes #42 +Closes #43 +``` + +### Size + +**Maximum 50 changed files per PR.** Split larger work. + +## Commits + +Conventional Commits, same type list as PR titles. Keep the subject under ~72 +characters and explain *why* in the body when it is not obvious from the diff. + +## Before opening a PR + +All three must pass locally — CI runs the same three: + +```bash +npm run build:headless # hermetic build +npm test # embedded web-fragment E2E +npx playwright test --config=playwright.config.ci.js # standalone fragment layer +``` + +The build and both suites are hermetic: they use the committed +`tests/fixtures/` artifacts via `apps.json`, so no `GITHUB_TOKEN`, no network and +no sibling repository is required. If a change makes any of them need network, +that is the bug — fix the change, not the test. + +`npm audit --omit=dev --audit-level=high` must also stay clean; it gates CI. + +## Repository conventions + +### Hermetic by construction + +`apps.json` is committed and CI builds from it. Entries pointing outside this +repository must carry `"optional": true` so a fresh clone still builds. Never +add a registry entry that requires network or a sibling checkout without it. + +### Two build modes, one document + +Every page renders through `src/layouts/Base.astro`. Headless (web-fragment) and +standalone differ only by `data-mp-headless` and the shadow-DOM compat styles — +not by a different layout. Changes that add a mode-specific code path need a +strong reason. + +### Light only + +The marketplace has no dark mode: no theme toggle, no persisted theme, no `dark` +class, no dark palette. `src/utils/transform.js` actively strips a sub-app's +theme bootstrap and `dark` body class. Do not reintroduce any of it. + +### Sub-app HTML is untrusted input + +Artifacts come from other repositories' releases. Treat their HTML, CSS and +archive contents as attacker-controlled: no unvalidated archive extraction, no +unsanitised HTML re-hosting, no shell interpolation of registry values. + +### Portability + +The build runs on Linux CI and on Windows developer machines. Prefer Node APIs +(`cpSync`, `rmSync`) over shelling out to `cp`/`rm`. Where `tar` is unavoidable, +follow the drive-letter workaround documented in +`scripts/build-vite.js` (`stageArtifact`). + +### Contract changes + +`contract/` is the public API for onboarding repositories. Changing +`schema.json`, `HEADLESS_RULES.md`, `STYLE_GUIDE.md` or `SINGLE_PAGE.md` is a +breaking change for every doc app — call it out explicitly in the PR +description. + +### Pinning + +Every GitHub Action is pinned to a commit SHA with the version in a trailing +comment. Keep it that way; Dependabot bumps them. + +## Aggregated PRs + +Grouping related issues into one PR is fine and often better than a chain of +one-line PRs. When doing so: + +- Group by **subsystem**, not by severity — reviewers read one area at a time. +- Reference every issue with its own `Closes #N` line. +- Keep the diff under the 50-file limit. +- Do not mix a security fix with an unrelated refactor; a reviewer should be + able to reason about the security change in isolation. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fef268e..1b23618 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,6 +17,11 @@ so no `GITHUB_TOKEN`, network, or sibling repository is required. See [`CLAUDE.md`](CLAUDE.md) for an architecture overview and the full command list, and [`README.md`](README.md) for usage. +[`AGENTS.md`](AGENTS.md) is the mechanical checklist for what CI enforces on a +pull request — branch name, title format, description, size — plus the +repository conventions a change is expected to respect. Worth a read before +opening your first PR, and required reading for automated contributors. + ## Tests | Command | What it runs |