Coding standards

Rules a reviewer applies to a diff. Anything a tool can check lives in .yamllint, .ansible-lint, or scripts/check.sh. This file covers the calls a tool cannot make.

Layout

A service directory is either flat or role-based. Pick by the service, not by taste.

Use the flat layout for one container plus a proxy:

service/
├── files/
├── vars/
│   └── default.yml
├── playbook.yml
└── readme.md

Use roles when the service has more than one container, unit, or stateful volume:

service/
├── roles/
│   ├── network/
│   ├── storage/
│   └── service/
├── vars/
│   └── default.yml
├── playbook.yml
└── readme.md

playbook.yml lists roles in dependency order. The data tier goes first, the app next, and the edge last. Each role has tasks/main.yaml. Add handlers/main.yaml and templates/ only when the role needs them.

Naming

playbook.yml, vars/default.yml, and readme.md in every service directory.
Role task and handler files use main.yaml. Playbook and vars files use .yml. This matches the existing tree. Do not rename either set in an unrelated change.
Handler names describe the action, for example "Restart Caddy", not the trigger.

YAML

Two-space indent, no tabs, LF line endings.
Quote Jinja values only when YAML would misread them.
Task names are sentence case and specific. "Create the data directory" is better than "Create directory".

Tasks

Prefer a module to command or shell. When a command is necessary, add creates, changed_when, or failed_when so a second run reports no change.
Put a long command string in files/ or a template.
A task that writes a config file notifies a handler. It does not restart the container inline.
Do not add ignore_errors to silence a check. Fix the task or narrow it.

Variables

Every variable a playbook needs has a value in vars/default.yml or a comment naming the host fact that supplies it.
Quote passwords so a leading 0 or a # survives YAML.
vars/default.yml is where this repo keeps deploy values, including passwords. Treat that file as sensitive. Rotate any value that leaks.

README

Each readme.md states what the playbook deploys, the variables the operator must set, and the command to run it. Link the upstream image or project.

Commits

One logical change per commit. Sentence case, imperative. Reference the issue when there is one, for example Closes #12.

2.5 KiB Raw Blame History