核心原则
- 使用约定式提交（Conventional Commits）规范
- 保持提交信息清晰、简洁、有意义
- 每个提交应该只做一件事
- 提交信息应解释"为什么"而不仅是"做了什么"
技术栈
- 版本控制：Git
- 规范：Conventional Commits
- 工具：commitlint, standard-version, semantic-release
- CI/CD：GitHub Actions / GitLab CI
最佳实践
提交消息格式
<类型>[可选范围]: <描述>
[可选正文]
[可选页脚]
类型说明
| 类型 |
描述 |
版本影响 |
feat |
新功能 |
MINOR |
fix |
Bug 修复 |
PATCH |
docs |
文档更新 |
- |
style |
代码格式（不影响逻辑） |
- |
refactor |
重构（不修复 Bug 也不添加功能） |
- |
perf |
性能优化 |
PATCH |
test |
添加或修改测试 |
- |
build |
构建系统或依赖更新 |
- |
ci |
CI 配置修改 |
- |
chore |
其他不修改 src 的更改 |
- |
示例
# 简单提交
feat: 添加用户登录功能
# 带范围的提交
feat(auth): 添加 OAuth2.0 认证支持
# 带 Breaking Change
feat(api)!: 重构 API 响应格式
BREAKING CHANGE: API 响应现在使用 { data, meta } 结构
# 带 Issue 引用
fix: 修复用户头像上传问题
Closes #123
正文规范
- 使用祈使语气："添加"而非"添加了"
- 首字母大写
- 不以句号结尾
- 限制首行 72 字符以内
- 正文说明更改的动机和对比
关键约定
- 破坏性变更
feat!: 移除旧版 API
BREAKING CHANGE: 所有 /v1/* 端点已被移除，请迁移至 /v2/*
- 多 Issue 关联
feat: 添加批量导出功能
Implements #100, #101
Related to #99
- Code Review 建议
refactor: 优化数据库查询性能
根据性能测试结果，将 N+1 查询优化为批量查询：
- 使用 select_related 减少 SQL 查询次数
- 添加数据库索引提升查询速度
Benchmark 结果：响应时间从 2s 降至 200ms
- 版本发布
# 使用 standard-version 自动生成 CHANGELOG
npm run release # 补丁版本
npm run release:minor # 次版本
npm run release:major # 主版本
配置示例
commitlint.config.js
module.exports = {
extends: ['@commitlint/config-conventional'],
rules: {
'type-enum': [
2,
'always',
['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore']
],
'subject-max-length': [2, 'always', 72]
}
};
.husky/commit-msg
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
npx --no -- commitlint --edit "$1"
工作流集成
GitHub Actions
name: Lint Commit Messages
on: [push, pull_request]
jobs:
commitlint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: wagoid/commitlint-github-action@v5
参考资料
liaosw97