81 lines
2.5 KiB
Markdown
81 lines
2.5 KiB
Markdown
# 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`.
|