homelab-infrastructure-as-code/CONVENTIONS.md

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.