boma/CONTRIBUTING.md

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

The master vault password lives in Vaultwarden; rbw fetches it on demand via scripts/vault-pass-client.sh (run rbw unlock once per session). Never put secrets in any file other than vault.yml.

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.