git-commit

Git Commit 标准

提交记录讲述着代码库的故事。好的提交历史胜过再多的文档——因为它始终保持最新。

社区默认规则。如果项目技能或 Agent 配置规则明确取代了 git-commit，则以该规则为准。

1. Conventional Commits 格式

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

[optional body]

[optional footer(s)]

类型：

Type	When
feat	新功能（对应 semver 中的 MINOR）
fix	Bug 修复（对应 semver 中的 PATCH）
refactor	既不修复 Bug 也不添加功能的代码变更
perf	性能改进
test	添加或修正测试
docs	仅修改文档
chore	构建流程、工具、依赖项
ci	CI/CD 配置变更
style	格式、空白字符（不是 CSS，而是代码格式）

范围：

使用包名或模块领域：

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(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. 提交消息规则

主题行：

• 使用祈使语气：“add feature”，不要写“added feature”或“adds feature”
• 类型前缀之后使用小写字母
• 末尾不加句号
• 最多 72 个字符
• 必须描述改了什么，而不是怎么改的

正文（需要时）：

• 主题行与正文之间空一行
• 说明为何需要此变更
• 从较高层面说明有哪些不同
• 每行最多 72 个字符

页脚：

• 引用问题：Fixes #123、Closes #456、Refs #789
• 共同作者：Co-authored-by: Name <email>
• 破坏性变更：BREAKING CHANGE: description

3. 示例

简单变更：

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

带正文：

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.

破坏性变更：

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

依赖项更新：

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. 原子提交

每次提交都应是一个独立的逻辑变更，并且：

• 可以独立编译（go build ./... 通过）
• 测试通过（go test ./... 通过）
• 可以独立撤销，而不影响其他变更

拆分大型变更：

# ❌ 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

5. 提交前验证

提交前，运行：

# Format and lint
goimports -w .
golangci-lint run

# Build
go build ./...

# Test
go test -race ./...

# Tidy modules
go mod tidy

如果任何步骤失败，请先修复再提交。绝不要提交损坏的代码，并想着“以后再修”——你不会修的。

6. 提交工作流

# Stage specific files (not 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

PR 前进行交互式变基：

交互式变基会打开 $EDITOR，因此 Agent 无法操作。先以非交互方式准备修正提交，然后将最后一步交给开发者：

# Mark a commit as a fixup of an earlier one (no editor)
git commit --fixup <sha>

# Collapse them automatically (no editor with --autosquash + GIT_SEQUENCE_EDITOR)
GIT_SEQUENCE_EDITOR=: git rebase -i --autosquash main

若要重新排序或改写提交消息，请让开发者自行运行 git rebase -i main，不要尝试代为操作。

7. 不要提交的内容

• 生成文件（除非必需，否则不要提交 *.pb.go、mocks/）
• IDE 配置（.idea/、.vscode/——使用全局 gitignore）
• 操作系统文件（.DS_Store、Thumbs.db）
• 二进制文件和构建产物
• 含有密钥的 .env 文件
• vendor/（除非项目策略明确要求）