From e830eb3b40811f891c3338e30c11c44227992535 Mon Sep 17 00:00:00 2001
From: kasun <kasun.jayatilaka@gmail.com>
Date: Tue, 28 Jul 2026 22:38:12 +0200
Subject: [PATCH] docs: add git conventions guide

---
 CONVENTIONS.md | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 CONVENTIONS.md

diff --git a/CONVENTIONS.md b/CONVENTIONS.md
new file mode 100644
index 0000000..92944b5
--- /dev/null
+++ b/CONVENTIONS.md
@@ -0,0 +1,63 @@
+# 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.