init

CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing
+
+## Code style
+
+- YAML files use 4-space indentation, formatted with `yamlfix`.
+- Jinja2 templates use the file extension `.j2`.
+- Role names use snake_case (e.g., `docker_registry`).
+- Task names are human-readable sentences (e.g., "Ensure SSL private keys are readable by containers").
+
+## Role structure
+
+Each role follows the standard Ansible layout:
+
+```
+roles/<name>/
+├── defaults/main.yml    # Default variables
+├── tasks/
+│   ├── main.yml         # Entry point
+│   └── *.yml            # Additional task files (deploy, restore, etc.)
+├── templates/           # Jinja2 templates (.j2)
+├── files/               # Static files
+└── meta/main.yml        # Role dependencies
+```
+
+## Adding a new service
+
+1. Create a new role in `ansible/roles/<service>/`.
+2. Add it to the proxy or IDP play in `ansible/playbooks/setup.yml` with a
+   `tags: [<service>]` annotation.
+3. If the role depends on docker or apache, those roles handle themselves
+   internally — just declare the dependency in `meta/main.yml`.
+## Testing changes
+
+Always test locally before deploying to production:
+
+```bash
+# Run against local VMs
+pipenv run ansible-playbook -i ansible/inventories/debug/hosts.ini ansible/playbooks/setup.yml \
+    --tags <service>
+```
+
+## Committing
+
+- Keep commits focused: one logical change per commit.
+- Use conventional-ish commit messages:
+  - `feat: add offline email notifications to prosody`
+  - `fix: correct registry vhost name collision`
+  - `chore: migrate collection roles to local roles/`
+
+## Vault changes
+
+When adding new secrets, add them to the vault file and document the variable
+name (but not the value) somewhere discoverable — either in the role's
+`defaults/main.yml` as a commented placeholder or in the playbook next to the
+role invocation.