git-commit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Commit Standards

Git提交规范

Commits tell the story of your codebase. A good commit history is worth more than any amount of documentation — because it's always up to date.

提交记录讲述着代码库的发展历程。一份优质的提交历史比任何文档都更有价值——因为它始终是最新的。

1. Conventional Commits Format

1. Conventional Commits格式

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

<type>(<scope>): <description>

[可选正文]

[可选页脚]

Types:

类型：

Type	When
`feat`	New feature (correlates with MINOR in semver)
`fix`	Bug fix (correlates with PATCH in semver)
`refactor`	Code change that neither fixes a bug nor adds a feature
`perf`	Performance improvement
`test`	Adding or correcting tests
`docs`	Documentation changes only
`chore`	Build process, tooling, dependencies
`ci`	CI/CD configuration changes
`style`	Formatting, whitespace (not CSS — code formatting)

类型	使用场景
`feat`	新功能（对应semver中的MINOR版本）
`fix`	修复Bug（对应semver中的PATCH版本）
`refactor`	既不修复Bug也不添加新功能的代码变更
`perf`	性能优化
`test`	添加或修正测试
`docs`	仅修改文档
`chore`	构建流程、工具、依赖相关变更
`ci`	CI/CD配置变更
`style`	代码格式、空白字符调整（非CSS样式——指代码格式化）

Scope:

范围：

Use the package name or module area:

feat(auth): add JWT refresh token rotation
fix(store/postgres): handle connection pool exhaustion
refactor(service): extract validation into dedicated package
test(handler): add table-driven tests for user endpoints
chore(deps): bump go.uber.org/zap to v1.27.0

使用包名或模块区域：

feat(auth): add JWT refresh token rotation
fix(store/postgres): handle connection pool exhaustion
refactor(service): extract validation into dedicated package
test(handler): add table-driven tests for user endpoints
chore(deps): bump go.uber.org/zap to v1.27.0

Breaking changes:

破坏性变更：

feat(api)!: change pagination from offset to cursor-based

BREAKING CHANGE: The `offset` and `limit` query parameters are replaced
by `cursor` and `page_size`. All existing clients must migrate.

feat(api)!: change pagination from offset to cursor-based

BREAKING CHANGE: The `offset` and `limit` query parameters are replaced
by `cursor` and `page_size`. All existing clients must migrate.

2. Commit Message Rules

2. 提交信息规则

Subject line:

主题行：

Imperative mood: "add feature", NOT "added feature" or "adds feature"
Lowercase after type prefix
No period at the end
Max 72 characters
Must describe WHAT changed, not HOW

使用祈使语气："add feature"，而非"added feature"或"adds feature"
类型前缀后使用小写
结尾不加句号
最多72个字符
必须描述做了什么变更，而非如何实现

Body (when needed):

正文（必要时使用）：

Blank line between subject and body
Explain WHY the change was necessary
Explain WHAT is different at a high level
Wrap at 72 characters

主题和正文之间空一行
解释变更的必要性
从宏观层面说明变更带来的不同之处
每行不超过72个字符

Footer:

页脚：

Reference issues:
```
Fixes #123
```
,
```
Closes #456
```
,
```
Refs #789
```
Co-authors:
```
Co-authored-by: Name <email>
```
Breaking changes:
```
BREAKING CHANGE: description
```

关联Issue：
```
Fixes #123
```
、
```
Closes #456
```
、
```
Refs #789
```
协作者：
```
Co-authored-by: Name <email>
```
破坏性变更：
```
BREAKING CHANGE: description
```

3. Examples

3. 示例

Simple change:

简单变更：

fix(handler): return 404 instead of 500 for missing user

fix(handler): return 404 instead of 500 for missing user

With body:

带正文的变更：

refactor(service): replace manual SQL with sqlx named queries

The raw SQL string concatenation for dynamic WHERE clauses was
error-prone and difficult to maintain. sqlx named queries provide
the same flexibility with automatic parameter binding.

No behavior change — all existing tests pass.

refactor(service): replace manual SQL with sqlx named queries

The raw SQL string concatenation for dynamic WHERE clauses was
error-prone and difficult to maintain. sqlx named queries provide
the same flexibility with automatic parameter binding.

No behavior change — all existing tests pass.

Breaking change:

破坏性变更：

feat(config)!: migrate from YAML to environment variables

BREAKING CHANGE: Configuration is now loaded from environment
variables instead of config.yaml. See README.md for the full
list of supported variables.

Closes #234

feat(config)!: migrate from YAML to environment variables

BREAKING CHANGE: Configuration is now loaded from environment
variables instead of config.yaml. See README.md for the full
list of supported variables.

Closes #234

Dependency update:

依赖更新：

chore(deps): upgrade pgx to v5.5.0

Picks up connection pool improvements and fixes for
COPY protocol handling. See release notes:
https://github.com/jackc/pgx/releases/tag/v5.5.0

chore(deps): upgrade pgx to v5.5.0

Picks up connection pool improvements and fixes for
COPY protocol handling. See release notes:
https://github.com/jackc/pgx/releases/tag/v5.5.0

4. Atomic Commits

4. 原子化提交

Each commit should be ONE logical change that:

Compiles on its own (
```
go build ./...
```
passes)
Tests pass (
```
go test ./...
```
passes)
Can be reverted independently without breaking other changes

每个提交应对应一个逻辑变更，满足：

可独立编译通过（
```
go build ./...
```
执行成功）
测试全部通过（
```
go test ./...
```
执行成功）
可独立回滚且不影响其他变更

Split large changes:

拆分大型变更：

undefined

undefined

❌ Bad — one commit doing everything

❌ 错误——一个提交包含所有内容

feat(user): add user management with CRUD, validation, auth, and tests

✅ Good — atomic, reviewable commits

✅ 正确——原子化、便于审查的提交

feat(domain): add User entity and validation rules feat(store): implement PostgreSQL user repository feat(service): add user service with create and get operations feat(handler): add REST endpoints for user management test(service): add table-driven tests for user creation docs(api): document user endpoints in OpenAPI spec

undefined

undefined

5. Pre-Commit Verification

5. 提交前校验

Before committing, run:

bash

undefined

提交前请执行以下命令：

bash

undefined

Format and lint

格式化与代码检查

goimports -w . golangci-lint run

Build

构建

go build ./...

Test

测试

go test -race ./...

Tidy modules

整理模块依赖

go mod tidy


If any step fails, fix before committing. Never commit broken code
with "will fix later" — you won't.

go mod tidy


如果任何步骤失败，请修复后再提交。绝对不要提交可运行的错误代码并标注"稍后修复"——你大概率不会去做。

6. Commit Workflow

6. 提交流程

bash

undefined

bash

undefined

Stage specific files (not git add .)

暂存指定文件（不要用git add .）

git add internal/service/user.go git add internal/service/user_test.go

Review staged changes

查看暂存的变更

git diff --staged

Commit with message

提交并添加信息

git commit -m "feat(service): add user creation with email validation"

Or use editor for longer messages

或者使用编辑器编写更长的信息

git commit # opens $EDITOR

undefined

git commit # 打开$EDITOR

undefined

Interactive rebase before PR:

提交PR前的交互式变基：

bash

undefined

bash

undefined

Clean up commit history before opening PR

打开PR前整理提交历史

git rebase -i main

Squash fixup commits

合并修正提交

Reword unclear messages

修改不清晰的提交信息

Reorder for logical flow

调整提交顺序以保证逻辑流畅

undefined

undefined

7. What NOT to Commit

7. 禁止提交的内容

Generated files (
```
*.pb.go
```
unless required,
```
mocks/
```
)
IDE configuration (
```
.idea/
```
,
```
.vscode/
```
— use global gitignore)
OS files (
```
.DS_Store
```
,
```
Thumbs.db
```
)
Binaries and build artifacts
```
.env
```
files with secrets
```
vendor/
```
(unless explicitly required by project policy)

生成的文件（除非项目要求，否则
```
*.pb.go
```
、
```
mocks/
```
等）
IDE配置文件（
```
.idea/
```
、
```
.vscode/
```
——请使用全局gitignore）
系统文件（
```
.DS_Store
```
、
```
Thumbs.db
```
）
二进制文件与构建产物
包含敏感信息的
```
.env
```
文件
```
vendor/
```
目录（除非项目政策明确要求）