Add the documentation and the agent instructions

README for humans, AGENTS.md for agents and contributors, and the docs that outlive any one platform: architecture, secrets, connectivity, triggering a deploy from another repository. CLAUDE.md, GEMINI.md and .claude/skills/ are pointers rather than copies, so every agent and every human reads the same text. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
2026-09-16 03:58:24 +02:00
parent 971034e630
commit e1f152ec3e
12 changed files with 1307 additions and 0 deletions
@@ -0,0 +1,62 @@
+# Contributing
+
+## Running the checks
+
+One command, and it is the same one CI runs:
+
+```bash
+make check          # or: scripts/check.sh
+```
+
+It runs `yamllint` over the repository, installs the Galaxy collections, runs
+`ansible-lint` at the `production` profile, and syntax-checks every playbook.
+
+Locally it reaches for [`uv`](https://docs.astral.sh/uv/) so this repository
+needs no virtualenv of its own. If you already have the tools on `PATH`, use
+`RUNNER=installed scripts/check.sh` to skip that.
+
+The version pins live in `scripts/check.sh` and nowhere else; both CI
+configurations ask the script for them, so a workflow cannot drift from what you
+ran locally.
+
+**Lint and syntax-check are the definition of done for a playbook.** They are
+static and safe.
+
+## What the checks will not catch
+
+Nothing here talks to a host, so the gate cannot tell you that a deploy works.
+Before proposing a change to a playbook, run it against your own host with
+`--check --diff` and say in the pull request what it reported. If you cannot,
+say that too — it is useful information, and better than an implied claim.
+
+## Conventions
+
+They are in [`AGENTS.md`](AGENTS.md), which is written for AI agents and is
+equally the contributor guide. The short version:
+
+- One playbook per stack, self-contained, tagged with the stack name.
+- Reuse goes in the `compose_stack` role's variable contract, not in copy-pasted
+  tasks or a second role.
+- Modules, not `shell`. Fully-qualified collection names. Every task named.
+- A second run must report zero changes.
+- No secrets in the repository — not in a `.env`, and especially not inline in a
+  compose file. See [`docs/secrets.md`](docs/secrets.md).
+
+[`skills/adding-a-stack/SKILL.md`](skills/adding-a-stack/SKILL.md) is the
+step-by-step version for the most common change.
+
+## Changing the examples
+
+The six example stacks exist to demonstrate specific features of the role
+contract — the table in [`server/README.md`](server/README.md) says which. If you
+change one, check that whatever it was demonstrating is still demonstrated
+somewhere, or the documentation that points at it stops being true.
+
+New examples are welcome if they show something the current six do not. An
+example that shows the same thing a seventh way is a cost, not a contribution.
+
+## Reporting a security issue
+
+Do not open a public issue for a vulnerability. Note that the example
+credentials, hostnames and addresses in this repository are all fictional;
+`example.com` is reserved by RFC 2606 and cannot resolve.