# Naming conventions

**Date:** 2026-01-10  
**Status:** Approved  
**Author:** Chester + FrankGPT

## Purpose

Consistent naming reduces cognitive load, prevents errors, and makes the codebase navigable for future contributors (including future-you).

---

## General principles

1. **Be descriptive:** Names should explain *what* something is or *what* it does.
2. **Be consistent:** Once you pick a pattern, stick to it everywhere.
3. **Avoid abbreviations:** Write `network` not `net`, `manager` not `mgr` — unless the abbreviation is industry-standard (e.g., `vm`, `ip`, `ssh`).
4. **Use English:** All identifiers, comments, and documentation in English.

---
## Files and folders

| Element | Convention | Example |
| :--- | :--- | :--- |
| Folders | lowercase, singular noun | `docker/`, `proxmox/`, `onboarding/` |
| Playbooks | `snake_case.yml` | `provision_swarm_vms.yml` |
| Roles | `snake_case` | `proxmox_post_install` |
| Templates | `filename.ext.j2` | `docker-compose.yml.j2` |
| Variable files | `snake_case.yml` | `swarm_defaults.yml` |

### Playbook naming pattern

Use **verb + object** format:

| Verb | Use when | Example |
| :--- | :--- | :--- |
| `provision_` | Creating infrastructure | `provision_swarm_vms.yml` |
| `configure_` | Modifying settings | `configure_nas.yml` |
| `deploy_` | Pushing applications | `deploy_portainer.yml` |
| `init_` | First-time setup | `init_cluster.yml` |
| `update_` | Applying updates | `update_containers.yml` |
| `validate_` | Checking correctness | `validate_karakeep.yml` |
| `test_` | Running tests | `test_ollama.yml` |
| `enforce_` | Ensuring compliance | `enforce_access.yml` |
| `remove_` | Deleting resources | `remove_old_images.yml` |

**Exceptions:** Master/orchestrator playbooks may be named after their target scope:
- `proxmox_host.yml` — orchestrates full PVE onboarding
- `ai_workstation.yml` — orchestrates AI host setup

---

## Inventory

| Element | Convention | Example |
| :--- | :--- | :--- |
| Group names | `snake_case` | `proxmox_cluster`, `swarm_managers` |
| Hostnames | `kebab-case` | `pve-01`, `swarm-manager-1` |
| Child groups | `parent:children` syntax | `ubuntu_lab:children` |

### Hostname pattern

```
<role>-<index>
```

| Role | Pattern | Examples |
| :--- | :--- | :--- |
| Proxmox hosts | `pve-0X` | `pve-01`, `pve-02` |
| Swarm managers | `swarm-manager-X` | `swarm-manager-1` |
| Swarm workers | `swarm-worker-X` | `swarm-worker-1` |
| AI workstations | `ai-<name>` | `ai-lenovo`, `ai-surface1` |
| Docker hosts | `<name>` or `docker-0X` | `waldorf`, `docker-01` |
| Storage | `<product>` | `synology`, `terramaster` |

---

## Variables

| Element | Convention | Example |
| :--- | :--- | :--- |
| All variables | `snake_case` | `vm_disk_size` |
| Role defaults | Prefix with role name | `proxmox_post_install_enabled` |
| Boolean vars | Use positive names | `enable_ha` (not `disable_ha`) |
| List vars | Plural nouns | `required_packages`, `allowed_users` |
| Dict vars | Singular noun | `vm_config`, `network_settings` |

### Variable prefixes by scope

| Scope | Prefix | Example |
| :--- | :--- | :--- |
| Role-specific | `<role>_` | `proxmox_post_install_enabled` |
| Playbook-local | `_` (single underscore) | `_temp_file` |
| Global/shared | none | `ansible_user`, `ssh_key_path` |

### Reserved variable names

Never override these Ansible built-ins:
- `inventory_hostname`, `ansible_host`, `ansible_user`
- `ansible_become`, `ansible_become_pass`
- `hostvars`, `groups`, `group_names`

---

## Tasks and handlers

| Element | Convention | Example |
| :--- | :--- | :--- |
| Task names | Sentence case, descriptive | `Install required packages` |
| Handler names | `Restart <service>` or `Reload <service>` | `Restart docker` |
| Block names | `<Action> <scope>` | `Configure SSH access` |
| Tags | `snake_case`, short | `install`, `configure`, `test` |

### Task naming rules

1. **Start with a verb:** `Install`, `Configure`, `Create`, `Remove`, `Ensure`, `Check`
2. **Be specific:** `Install Docker CE` not `Install Docker`
3. **No trailing punctuation:** `Install packages` not `Install packages.`
4. **Use present tense:** `Create user` not `Created user`

---

## Tags

Use tags to allow selective execution:

| Tag | Purpose | Example usage |
| :--- | :--- | :--- |
| `install` | Package installation | `--tags install` |
| `configure` | Configuration changes | `--tags configure` |
| `test` | Validation/testing | `--tags test` |
| `cleanup` | Removal/pruning | `--tags cleanup` |
| `never` | Skip unless explicit | `--tags never,dangerous_task` |

---

## Secrets and sensitive data

| Element | Convention | Example |
| :--- | :--- | :--- |
| Vault files | `vault_<scope>.yml` | `vault_production.yml` |
| Secret vars | Suffix with `_secret` or `_pass` | `db_password`, `api_key_secret` |
| Encrypted strings | Use `!vault` tag | `password: !vault |...` |

---

## Git branches (if applicable)

| Branch | Purpose |
| :--- | :--- |
| `main` | Production-ready playbooks |
| `develop` | Integration branch |
| `feature/<name>` | New features |
| `fix/<name>` | Bug fixes |
| `docs/<name>` | Documentation updates |

---

## Quick reference card

```
Files:         snake_case.yml
Folders:       lowercase/
Roles:         snake_case
Hostnames:     kebab-case
Groups:        snake_case
Variables:     snake_case
Tasks:         Sentence case, verb first
Tags:          snake_case
```

---

## References

- [Ansible Best Practices — Variable Naming](https://docs.ansible.com/ansible/latest/tips_tricks/ansible_tips_tricks.html)
- [Ansible Lint — Naming Rules](https://ansible.readthedocs.io/projects/lint/rules/name/)
- [Google Shell Style Guide](https://google.github.io/styleguide/shellguide.html) — for script naming inspiration