From f35612bc4a483df2fbc5e9bc3953f1979c9a54f4 Mon Sep 17 00:00:00 2001 From: moilanik Date: Thu, 9 Apr 2026 09:14:07 +0300 Subject: [PATCH] docs(git): prohibit file-by-file breakdowns in commit messages Update commit message guidelines to strictly forbid listing filenames or technical code edits in the body. The revised rules require describing the high-level topics and accomplished goals to ensure messages remain abstract and easily readable. --- .ai/instructions/skills/git.instructions.md | 44 ++++++++++----------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/.ai/instructions/skills/git.instructions.md b/.ai/instructions/skills/git.instructions.md index 89c7aaf..8aa185e 100644 --- a/.ai/instructions/skills/git.instructions.md +++ b/.ai/instructions/skills/git.instructions.md @@ -79,34 +79,34 @@ Types: `feat`, `fix`, `docs`, `refactor`, `chore` **Only include what actually changed in this commit.** - Run `git diff --staged` (or `git diff` if nothing staged) and read it fully before writing -- List only files and lines that appear in the diff -- If a file appears in the diff but only has whitespace or comment changes, omit it from the body - Never mention changes that are not in the diff — even if you remember discussing them earlier in the session - If unsure whether something changed, check the diff — do not guess **Format rules:** - Subject line: max ~72 chars, imperative mood ("Fix", "Add", "Remove" — not "Fixed", "Added") -- Body: optional, only when the *why* is not obvious from the diff -- No bullet-pointed list of every file changed unless the diff spans many unrelated files -- No "CHANGES:" headers, no file-by-file breakdowns for single-topic commits -- No "Expected:", "Result:", "Impact:" or any speculative outcome sections — commit messages describe what changed, not what is predicted to happen -- Bullet points state *what* changed, not *why it was wrong* or *how it works* — keep each line short and factual - - ✅ `use MC_HOST_minio for S3 auth` - - ❌ `Use MC_HOST_minio env var for direct S3 auth (no mc alias set)` +- Body: optional, only when the *intent* or *why* is not obvious from the diff +- **NEVER list filenames in the commit message.** The git UI already shows which files changed. Your job is to describe *topics*, not files. No file-by-file breakdowns, and no "CHANGES:" headers. +- **Translate technical changes into a high-level topic summarization.** A human reading the message should immediately understand *what the goal was* without having to interpret individual code or file edits. Describe the business/functional accomplishment, not the technical steps taken. + - ❌ `docs/ai-context.md: add homelab k3s target, domain pattern` + - ✅ `document development environment and deployment context` +- No "Expected:", "Result:", "Impact:" or any speculative outcome sections — commit messages describe the accomplished goal, not what is predicted to happen +- Bullet points state *the high-level topics*, not *technical line edits* or *how it works* — keep each line short and factual + - ✅ `configure direct S3 authentication for MinIO` + - ❌ `use MC_HOST_minio env var for direct S3 auth (no mc alias set)` - Do not describe runtime behavior, incident narrative, or manual operations in the commit message body - ❌ `gitea failed on startup` - ❌ `Redis services cleaned up manually` - ❌ `Certificate renewed successfully` - - ✅ `disable redis sub-chart` - - ✅ `set queue type to level` -- Do not summarize or quote the content of text/description changes — the diff shows the content, the message states that the change happened + - ✅ `disable external redis dependency` + - ✅ `configure queue type to persistent level` +- 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 - ❌ `Remove "harmless" framing, add operational guidance: daily return to 0 expected` - - ✅ `update Ghost Blocks panel description to reflect operational expectations` -- Body format: use prose (one sentence) for a single change; use bullets when there are multiple distinct changes + - ✅ `update operational expectations for Ghost Blocks panel` +- Body format: use prose (one sentence) for a single goal; use bullets ONLY when multiple completely distinct goals or topics were accomplished in the same commit. -**Body length example — what "too much explanation" looks like vs. the correct version:** +**Body length example — what "too much explanation" looks like vs. the correct abstract version:** -❌ Too long — describes runtime behavior, not the change: +❌ Too detailed — describes files, code references, and technical mechanics: ```text chore(minio): pin image to RELEASE.2025-10-15T17-29-55Z @@ -119,15 +119,15 @@ Also add comment on thanos-sidecar image noting all Thanos containers this single image reference. ``` -✅ Correct — states what changed, one line of context for the why: +✅ Correct — states the high-level intent and reasoning clearly without itemizing files or specific code additions: ```text -chore(minio): pin image to RELEASE.2025-10-15T17-29-55Z +chore(minio): downgrade minio version to fix object metadata loss -RELEASE.2024-12-18 (Chart 5.4.0) lacks Last-Modified on objects; compactor -deletes valid blocks as stale partial uploads. +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. -Add comment on thanos-sidecar: image is shared by compactor, blocks-exporter, -init container and ghost cleanup job. +Also clarified shared image dependencies for Thanos services in documentation. ``` **All projects:**