# 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`.