Lucas WintherandClaude Opus 5
e1f152ec3e
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]>
63 lines
2.5 KiB
Markdown
63 lines
2.5 KiB
Markdown
# 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.
|