sjat
703f1716e5
First /review-repo run on boma. Hardened repo-scan.py (no TODO.md/prose false positives). Applied 7 safe fixes (DNS staleness x2, STATUS factual correction, hosts.yml path generalisation, trunk-based wording x2, scripts/README). Recorded the run and 17 open findings in docs/reviews/2026-05-30-*. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
59 lines
1.9 KiB
Markdown
59 lines
1.9 KiB
Markdown
# Contributing
|
|
|
|
## Conventions
|
|
|
|
- All Ansible modules use FQCN: `ansible.builtin.template`, not `template`
|
|
- Every task has a `name:` that reads as a sentence and at least one tag
|
|
- Role variables use `rolename__varname` double-underscore namespace
|
|
- No plain text secrets outside `vault.yml` files
|
|
|
|
## Branching
|
|
|
|
Single-contributor, trunk-based:
|
|
|
|
- `main` is the trunk and must always work. Small, self-contained changes commit
|
|
straight to `main`.
|
|
- Use a short-lived branch for sweeping or AI-driven changes you want to review as
|
|
one diff or be able to abandon: `role/<name>`, `fix/<description>`,
|
|
`feat/<description>`, `chore/<description>`. Merge to `main` when it looks right,
|
|
then delete the branch.
|
|
- Run `make lint` (and `make test` for touched roles) before committing.
|
|
- Commit messages: imperative mood, ≤72-char subject; commit in logical units.
|
|
- Push to Forgejo often — it is the off-machine backup.
|
|
|
|
## Adding a role
|
|
|
|
Follow the runbook: `docs/runbooks/new-role.md`
|
|
|
|
Always use `make new-role NAME=<name>` to scaffold — never create structure by hand.
|
|
|
|
## Secrets
|
|
|
|
Vault password is shared via a secure channel (password manager).
|
|
Never commit `.vault_pass`. Never put secrets in non-`vault.yml` files.
|
|
|
|
See `docs/runbooks/rotate-secrets.md` for rotation procedures.
|
|
|
|
## Generated files
|
|
|
|
Some files are produced by tooling and must not be hand-edited — change the source
|
|
and regenerate. Each generated file carries a header saying so.
|
|
|
|
| Generated file | Source of truth | Regenerate with |
|
|
|---|---|---|
|
|
| `inventories/<env>/hosts.yml` | `terraform/environments/<env>/main.tf` (`local.vms`) | `make tf-inventory TF_ENV=<env>` |
|
|
|
|
Exception: the control node is added to `hosts.yml` by hand — see
|
|
`docs/runbooks/new-host.md`.
|
|
|
|
## Testing
|
|
|
|
Before committing or merging to main:
|
|
|
|
```bash
|
|
make lint
|
|
make test ROLE=<affected-role>
|
|
make check PLAYBOOK=site
|
|
```
|
|
|
|
All three must pass cleanly.
|