git-commit-quality

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Commit Quality Standards

Git 提交质量标准

Core Philosophy

核心原则

A Git commit message records the state change and its essential architectural rationale, not a development diary, proof-of-work ledger, or debugging scratchpad.

Default to a subject-only commit. Add a body only when the diff cannot convey a non-obvious invariant, business logic constraint, compatibility requirement, or issue reference.

Git 提交信息应记录状态变更及其关键架构依据，而不是开发日记、工作量账本或调试草稿。

默认采用仅包含主题行的提交信息。只有当 diff 无法体现不明显的不变量、业务逻辑约束、兼容性要求或 issue 引用时，才应添加正文。

1. Commit Format & Constraints

1. 提交格式与约束

Subject line:
- Imperative mood, present tense (
```
Add
```
  ,
```
Fix
```
  ,
```
Update
```
  ,
```
Refactor
```
  ,
```
Remove
```
  ), never
```
Added
```
  ,
```
Fixes
```
  , or
```
Updating
```
  .
- Under 50 characters (hard ceiling: 72 characters).
- Capitalize first letter; no trailing period.
- No conventional commit prefixes (
```
feat:
```
  ,
```
fix:
```
  ,
```
chore:
```
  ) unless repository conventions require them.
Subject-only default: If the diff and subject make the change evident, omit the body entirely.
Body:
- Separate from subject with a single blank line.
- 1 to 4 lines maximum, hard-wrapped at 72 characters.
- Focus strictly on why (non-obvious invariants, constraints, upstream quirks).
- Include issue-closing trailers when applicable (
```
Fixes #123
```
  ).
Granularity: Split unrelated changes into distinct commits rather than writing a multi-paragraph body explaining multiple unrelated edits.

主题行：
- 使用命令式语气和现在时（
```
Add
```
  、
```
Fix
```
  、
```
Update
```
  、
```
Refactor
```
  、
```
Remove
```
  ），绝不要使用
```
Added
```
  、
```
Fixes
```
  或
```
Updating
```
  。
- 少于 50 个字符（硬上限为 72 个字符）。
- 首字母大写；结尾不加句号。
- 除非仓库约定要求，否则不要使用 Conventional Commit 前缀（
```
feat:
```
  、
```
fix:
```
  、
```
chore:
```
  ）。
仅主题行默认格式： 如果 diff 和主题行已经清楚说明变更，应完全省略正文。
正文：
- 与主题行之间用一个空行分隔。
- 最多 1 至 4 行，按 72 个字符强制换行。
- 严格聚焦于变更的“为什么”，例如不明显的不变量、约束或上游的特殊行为。
- 适用时包含用于关闭 issue 的 trailers（
```
Fixes #123
```
  ）。
粒度： 将不相关的变更拆分为独立提交，而不是用多段正文解释多个互不相关的修改。

2. Commit Anti-Patterns

2. 提交反模式

1. The Development & Debugging Diary

1. 开发与调试日记

Anti-Pattern: Narrating the debugging journey, transient investigation findings, local benchmarks, or test run outputs ("verified today on live instance", "dummy DB had 76 orphaned rows", "typed from live response").

❌

text

Fix deleteThing endpoint after testing

deleteThing wraps /ajax/thing/delete/, verified today: it destroys the pool
row, so every level sharing it loses the row, and a repeat call answers 404.
Ran go test -race ./... locally and it passed in 1.2s.

✅

text

Fix deleteThing endpoint wrapper

Permanently deletes the shared pool record via /ajax/thing/delete/.

反模式： 叙述调试过程、临时调查发现、本地基准测试结果或测试运行输出（“今天已在实时实例上验证”、“虚拟数据库中有 76 行孤立记录”、“根据实时响应输入”）。

❌

text

Fix deleteThing endpoint after testing

deleteThing wraps /ajax/thing/delete/, verified today: it destroys the pool
row, so every level sharing it loses the row, and a repeat call answers 404.
Ran go test -race ./... locally and it passed in 1.2s.

✅

text

Fix deleteThing endpoint wrapper

Permanently deletes the shared pool record via /ajax/thing/delete/.

2. Request Accounting & Internal Plumbing Bloat

2. 请求核算与内部管道膨胀

Anti-Pattern: Explaining internal request counts, step-by-step pipeline routing, or unobservable backend minutiae.

❌

text

Cut the requests an item edit costs

A named single-cell edit was four requests on a cold client. Passing poolId
skips the lookup that finds the thing's pool, and verify: false drops the
read-back, so the floor is now one request; a warm client pays two.

✅

text

Optimize item edit request overhead

Add poolId and verify options to bypass pool lookup and verification
read-backs when updating items.

反模式： 解释内部请求次数、逐步骤的管道路由，或无法观测的后端琐碎细节。

❌

text

Cut the requests an item edit costs

A named single-cell edit was four requests on a cold client. Passing poolId
skips the lookup that finds the thing's pool, and verify: false drops the
read-back, so the floor is now one request; a warm client pays two.

✅

text

Optimize item edit request overhead

Add poolId and verify options to bypass pool lookup and verification
read-backs when updating items.

3. Defensive Post-Mortems & Apologies

3. 防御性事后复盘与道歉

Anti-Pattern: Explaining why the author or model made an earlier mistake, hallucinated an API, or misunderstood existing code.

❌

text

Fix route handling in auth middleware

My mistake on the earlier commit: I assumed Express stripped trailing
slashes automatically like Actix does, which broke the callback URL.

✅

text

Normalize trailing slashes in auth callback route

反模式： 解释作者或模型为何犯下先前的错误、虚构了 API，或误解了现有代码。

❌

text

Fix route handling in auth middleware

My mistake on the earlier commit: I assumed Express stripped trailing
slashes automatically like Actix does, which broke the callback URL.

✅

text

Normalize trailing slashes in auth callback route

4. Ghost Commentary & Tombstones

4. 幽灵评论与墓碑式说明

Anti-Pattern: Explaining what code used to do, why old deprecated functions were removed, or how the new approach differs from historical drafts.

❌

text

Update session store

We no longer use Redis for session storage because memory costs were too
high and DynamoDB provides TTL natively without custom maintenance jobs.

✅

text

Migrate session store from Redis to DynamoDB

Relies on native DynamoDB TTL for automatic session expiration.

反模式： 解释代码过去的行为、移除旧版弃用函数的原因，或新方案与历史草案之间的差异。

❌

text

Update session store

We no longer use Redis for session storage because memory costs were too
high and DynamoDB provides TTL natively without custom maintenance jobs.

✅

text

Migrate session store from Redis to DynamoDB

Relies on native DynamoDB TTL for automatic session expiration.

5. Absence Commentary & Omission Lists

5. 缺席评论与遗漏清单

Anti-Pattern: Listing hypothetical features or cleanup tasks deliberately not done ("Did not touch older models...", "Left open for later...").

❌

text

Add user avatar upload

Supports JPEG and PNG. I did not add WebP conversion or S3 upload logic
because that should be handled in a background worker later.

✅
text
```
Add JPEG and PNG user avatar upload
```

反模式： 列出刻意未实现的功能或未完成的清理任务（“未改动旧版模型……”、“留待后续处理……”）。

❌

text

Add user avatar upload

Supports JPEG and PNG. I did not add WebP conversion or S3 upload logic
because that should be handled in a background worker later.

✅
text
```
Add JPEG and PNG user avatar upload
```

6. AI Attribution & Watermarks

6. AI 署名与水印

Anti-Pattern: Appending

Co-authored-by: Claude <...>

Signed-off-by

AI bots, or

_Generated by..._

trailers.

❌

text

Update database migration scripts

Co-authored-by: Claude <noreply@anthropic.com>

✅
text
```
Update database migration scripts
```

反模式： 在末尾添加

Co-authored-by: Claude <...>

、AI bot 的

Signed-off-by

或

_Generated by..._

等 trailers。

❌

text

Update database migration scripts

Co-authored-by: Claude <noreply@anthropic.com>

✅
text
```
Update database migration scripts
```

7. Rule Compliance & Meta-Reporting

7. 规则合规与元报告

Anti-Pattern: Referencing instructions, linters, or skill compliance in commit text ("Fix lint errors and remove all em dashes per guidelines").
❌
text
```
Clean up comments per skill guidelines
```

✅

text

Remove obsolete comments and normalize docstring formatting

反模式： 在提交文本中提及指令、linters 或 skill 合规情况（“按照 skill 指南修复 lint 错误并移除所有 em dash”）。
❌
text
```
Clean up comments per skill guidelines
```

✅

text

Remove obsolete comments and normalize docstring formatting

3. Style, Punctuation & Precision

3. 风格、标点与准确性

Zero conversational dashes: Never use em dashes (
```
—
```
), en dashes (
```
–
```
), or double hyphens (
```
--
```
) as conversational pauses. Use commas, colons, parentheses, or separate sentences.
No hype or synthetic fillers: Cut crucial, seamless, robust, game-changer, pivotal, unlock.
No staged rhetoric: Do not use throat-clearing, theatrical openings, rhetorical questions, defensive rebuttals, generic positive endings, punchy fragments, or antithesis to create emphasis.
Preserve exact literals & uncertainty: Keep exact identifiers, issue numbers, configuration flags, commands, and error codes. Do not turn conditional possibilities ("may prevent timeout under load") into universal guarantees ("guarantees zero timeouts").
Keep formatting plain: Avoid decorative formatting, emojis, and forced lists. Each sentence must state a concrete change, durable constraint, or issue reference.

Rewrite the whole subject or body around its essential fact. Do not replace individual AI-sounding words while retaining the same padded structure.

零对话式破折号： 绝不要使用 em dash（
```
—
```
）、en dash（
```
–
```
）或双连字符（
```
--
```
）作为会话停顿。改用逗号、冒号、括号或独立句子。
不使用炒作性或人为填充的词语： 删去 crucial, seamless, robust, game-changer, pivotal, unlock 等词语。
不使用戏剧化修辞： 不要使用拖沓的开场、戏剧化的开头、反问、防御性反驳、泛泛的正面收尾、故作有力的残句，或通过对仗制造强调。
保留准确的字面量与不确定性表达： 保留确切的标识符、issue 编号、配置标志、命令和错误码。不要把有条件的可能性（“可能防止负载下超时”）变成普遍保证（“保证零超时”）。
保持格式朴素： 避免装饰性格式、emoji 和强制列表。每个句子都必须陈述具体变更、持久约束或 issue 引用。

围绕核心事实重写整个主题行或正文。不要只替换个别听起来像 AI 的词，却保留同样臃肿的结构。

4. Audit Findings Format

4. 审计发现格式

When reviewing or auditing existing commit history, report findings in this structure:

markdown

undefined

审查或审计现有提交历史时，按以下结构报告发现：

markdown

undefined

Commit

<commit-sha>

<Subject line>

Commit

<commit-sha>

<Subject line>

Original:
text
```
<Exact original subject and body>
```
Anti-Pattern:
```
<Name of violated anti-pattern(s)>
```

Issue:

<1-sentence explanation of why it is low-signal or padded>

Replacement:

text

<Clean proposed subject line>

<Clean proposed body wrapped at 72 chars, or omit if subject-only>

undefined

Original:
text
```
<Exact original subject and body>
```
Anti-Pattern:
```
<Name of violated anti-pattern(s)>
```

Issue:

<1-sentence explanation of why it is low-signal or padded>

Replacement:

text

<Clean proposed subject line>

<Clean proposed body wrapped at 72 chars, or omit if subject-only>

undefined

git-commit-quality

Original

Translation

Git Commit Quality Standards

Git 提交质量标准

Core Philosophy

核心原则

1. Commit Format & Constraints

1. 提交格式与约束

2. Commit Anti-Patterns

2. 提交反模式

1. The Development & Debugging Diary

1. 开发与调试日记

2. Request Accounting & Internal Plumbing Bloat

2. 请求核算与内部管道膨胀

3. Defensive Post-Mortems & Apologies

3. 防御性事后复盘与道歉

4. Ghost Commentary & Tombstones

4. 幽灵评论与墓碑式说明

5. Absence Commentary & Omission Lists

5. 缺席评论与遗漏清单

6. AI Attribution & Watermarks

6. AI 署名与水印

7. Rule Compliance & Meta-Reporting

7. 规则合规与元报告

3. Style, Punctuation & Precision

3. 风格、标点与准确性

4. Audit Findings Format

4. 审计发现格式

Commit
`<commit-sha>`
:
`<Subject line>`

Commit
`<commit-sha>`
:
`<Subject line>`

git-commit-quality

Original

Translation

Git Commit Quality Standards

Git 提交质量标准

Core Philosophy

核心原则

1. Commit Format & Constraints

1. 提交格式与约束

2. Commit Anti-Patterns

2. 提交反模式

1. The Development & Debugging Diary

1. 开发与调试日记

2. Request Accounting & Internal Plumbing Bloat

2. 请求核算与内部管道膨胀

3. Defensive Post-Mortems & Apologies

3. 防御性事后复盘与道歉

4. Ghost Commentary & Tombstones

4. 幽灵评论与墓碑式说明

5. Absence Commentary & Omission Lists

5. 缺席评论与遗漏清单

6. AI Attribution & Watermarks

6. AI 署名与水印

7. Rule Compliance & Meta-Reporting

7. 规则合规与元报告

3. Style, Punctuation & Precision

3. 风格、标点与准确性

4. Audit Findings Format

4. 审计发现格式

Commit <commit-sha>: <Subject line>

Commit <commit-sha>: <Subject line>

Commit
`<commit-sha>`
:
`<Subject line>`

Commit
`<commit-sha>`
:
`<Subject line>`