61 lines
3.3 KiB
Markdown
61 lines
3.3 KiB
Markdown
# Git & Commit Message Reference Guide
|
|
|
|
This document contains detailed examples and rationales for the `ai-superpower` Git commit message standards.
|
|
|
|
## The Core Philosophy
|
|
|
|
Commit messages describe **topics and goals**, not filenames and line edits. The Git UI already perfectly documents *which* files changed and *what* code was added or removed. The commit message's job is to explain *why* the change was made and *what* the high-level business or architectural intention was.
|
|
|
|
## Formatting Rules Deep Dive
|
|
- **Subject line**: Max ~72 characters, imperative mood ("Fix", "Add", "Remove" — not "Fixed", "Added").
|
|
- **Body**: Optional. Use only when the *intent* or *why* is not obvious from the diff.
|
|
- **Never list filenames**. Do not use "CHANGES:" headers or file-by-file breakdowns.
|
|
- **Translate technical changes into a high-level topic summarization.**
|
|
- **No speculative outcomes.** No "Expected:", "Result:", or "Impact:" sections.
|
|
- **Do not describe runtime behavior, incident narrative, or manual operations** in the commit message body.
|
|
- **Do not summarize or quote the exact content of text/description changes.** The diff shows the content; the message states the topic of the change.
|
|
|
|
## ✅ / ❌ Commit Message Patterns
|
|
|
|
### High-level Topics vs. Technical Steps
|
|
- ❌ `docs/ai-context.md: add homelab k3s target, domain pattern` *(Mentions filenames, reads like a technical log)*
|
|
- ✅ `document development environment and deployment context` *(Abstracts to the goal)*
|
|
|
|
### Bullet Points State Topics, Not Implementation
|
|
- ❌ `use MC_HOST_minio env var for direct S3 auth (no mc alias set)` *(Describes the exact code change)*
|
|
- ✅ `configure direct S3 authentication for MinIO` *(Describes the architectural goal)*
|
|
|
|
### No Runtime/Status Narratives
|
|
- ❌ `gitea failed on startup` *(Describes an incident, not the repo state change)*
|
|
- ❌ `Redis services cleaned up manually` *(Describes a manual ops task)*
|
|
- ✅ `disable external redis dependency` *(Describes what the commit actually does to the code)*
|
|
|
|
### No Quoting the Text Changes
|
|
- ❌ `Remove "harmless" framing, add operational guidance: daily return to 0 expected` *(Quotes the diff directly)*
|
|
- ✅ `update operational expectations for Ghost Blocks panel` *(States the topic of the documentation update)*
|
|
|
|
### Body Length and Verbosity Example
|
|
|
|
❌ **Too detailed** — describes files, code references, and technical mechanics:
|
|
```text
|
|
chore(minio): pin image to RELEASE.2025-10-15T17-29-55Z
|
|
|
|
Chart 5.4.0 bundles RELEASE.2024-12-18 which does not return Last-Modified
|
|
metadata on objects. Thanos compactor falls back to ULID creation time and
|
|
deletes valid blocks as stale partial uploads (>48h old).
|
|
|
|
Also add comment on thanos-sidecar image noting all Thanos containers
|
|
(compactor, blocks-exporter, init container, ghost cleanup job) share
|
|
this single image reference.
|
|
```
|
|
|
|
✅ **Correct** — states the high-level intent and reasoning clearly without itemizing files or specific code additions:
|
|
```text
|
|
chore(minio): downgrade minio version to fix object metadata loss
|
|
|
|
The newer chart release causes valid block deletion by the compactor due
|
|
to missing Last-Modified metadata on objects. Version is pinned to an
|
|
older stable release to prevent data loss.
|
|
|
|
Also clarified shared image dependencies for Thanos services in documentation.
|
|
``` |