# 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.