sjat/boma

sjat 703f1716e5 review-repo: harden scanner, apply safe fixes, record first review

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>

2026-05-30 19:10:58 +02:00

1.9 KiB

Raw Blame History

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:

make lint
make test ROLE=<affected-role>
make check PLAYBOOK=site

All three must pass cleanly.

1.9 KiB Raw Blame History