64 lines
2.5 KiB
Markdown
64 lines
2.5 KiB
Markdown
# 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.
|