# Git Conventions

## Branch Naming

```
<type>/<short-kebab-case-description>
```

- All lowercase, hyphens only — no camelCase or Title-Case
- Keep the description short (3–5 words); the branch name is not the place for detail
- No ticket tracker is used on this project, so branch names don't carry an ID

| Type | Use for |
|---|---|
| `feature/` | New functionality (e.g. a new stack, a new resource type) |
| `bug/` | Bug fixes |
| `enhancement/` | Improvements or refactors to existing functionality, no new capability |
| `chore/` | Dependency bumps, tooling, CI/CD, cleanup |
| `docs/` | Documentation only (README, CLAUDE.md files) |

**Examples:** `feature/add-3rd-proxmox-node`, `bug/fix-longhorn-disk-pressure`, `enhancement/refactor-k8s-bootstrap`

---

## Commit Messages

```
<type>: <imperative, present-tense summary>

<optional body — explain WHY, not WHAT>
```

- **Type** — same list as branch types above (`feature`, `bug`, `enhancement`, `chore`, `docs`)
- **Scope is optional** and, if used, should be one of the stack directories this repo is organized into — `proxmox-infra`, `k8s-bootstrap`, `k8s-infra`, `k8s-apps`, `monitoring` — or `ci` for `.gitea/workflows` changes: `fix(k8s-infra): ...`
- **Summary** — imperative mood ("add", not "added" or "adds"); no period at the end
- **Body** — only when the reasoning isn't obvious from the diff (a constraint, a workaround for a Proxmox/k3s quirk, a decision between StackReference outputs). Skip it for simple/self-explanatory changes.

**Examples:**
```
feature: add pfsense provider for automating static IP setup
bug: prune stale kube-vip leases after node replacement
chore: upgrade Pulumi provider packages across all stacks
docs: update CLAUDE.md with new Longhorn mount settings
enhancement(k8s-bootstrap): cache dependencies to speed up deployment
```

---

## Pull Request Titles

This repo uses Gitea Actions (see root `CLAUDE.md`); Gitea's merge commit reuses the PR title verbatim as the merge summary, so the title should stand on its own in `git log`. Frame it as the outcome, not a task log:

```
<Type>: <what changes for the cluster/infra>
```

**Examples:**
- `Feature: Add 3rd Proxmox node to the cluster`
- `Bug: Fix Longhorn disk pressure from root disk usage`
- `Enhancement: Refactor k8s-bootstrap for clearer deployment order`
- `Chore: Upgrade Pulumi packages across all stacks`

Since `01`/`02` deploys are manual (`workflow_dispatch`) and `03`–`05` deploy on merge to `main`, a clear PR title also doubles as a quick changelog of what just went live.