提交消息编写规范

提交消息编写规范的重要性

好的提交消息能帮助团队理解代码变更的意图和历史。清晰的提交历史让代码审查、问题追踪和版本回退更加高效。混乱的提交消息会增加维护成本，降低协作效率。

提交消息的基本结构

标准的提交消息包含三个部分：标题、正文和页脚。标题是简短描述，正文详细说明变更原因和内容，页脚包含引用或元数据。

fix: 修复用户登录失败的问题

当用户密码包含特殊字符时，后端API返回500错误。
修改了密码验证逻辑，现在能正确处理特殊字符。

Closes #123

标题规范

标题行限制在50个字符以内，使用命令式现在时态。第一个单词首字母小写，结尾不加句号。常见前缀包括：

• feat: 新功能
• fix: 错误修复
• docs: 文档变更
• style: 代码格式调整
• refactor: 重构代码
• test: 测试相关
• chore: 构建过程或辅助工具变更

错误示例：

Fixed the bug  # 使用过去时
用户模块优化  # 缺少类型前缀

正文编写要点

正文每行不超过72个字符，解释"为什么"要修改而非"改了什么"。描述变更的动机和与之前行为的对比。复杂变更可以分点说明：

feat: 添加购物车批量删除功能

- 用户现在可以同时选择多个商品进行删除
- 新增了全选/取消全选复选框
- 后端API新增批量删除接口/cart/items/batch
- 前端添加了确认对话框防止误操作

之前只能单件删除，批量操作需要多次请求。
电商大促期间用户反馈删除效率太低。

页脚格式

页脚包含issue跟踪、破坏性变更说明或协作者信息。使用关键字关联issue：

BREAKING CHANGE: 配置文件结构重构，需更新.env文件
See also: #45, #78
Co-authored-by: John <john@example.com>

特殊情况处理

多提交关联

大型功能拆分多个提交时，在正文注明关联关系：

refactor: 用户模块数据层重构 (1/3)

这是用户模块重构的第一部分，包含：
- 抽离数据库访问逻辑
- 统一错误处理机制

后续提交：
2/3 将更新业务逻辑层
3/3 将修改API接口层

紧急修复

热修复(hotfix)需要标明优先级：

fix: 紧急修复支付超时问题 [P0]

支付网关接口超时设置错误导致订单失败率上升。
立即回滚了错误配置，恢复为30秒超时。

Root cause: 部署脚本错误覆盖了配置

自动化工具推荐

使用commitlint确保消息规范：

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'header-max-length': [2, 'always', 72],
    'body-max-line-length': [2, 'always', 72]
  }
}

结合husky添加Git钩子：

// package.json
{
  "husky": {
    "hooks": {
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  }
}

团队协作建议

1. 新成员入职时进行提交规范培训
2. 代码审查时检查提交消息质量
3. 定期整理提交历史，合并琐碎提交
4. 复杂功能使用开发分支，通过PR合并

示例不良提交及改进：

// 不良提交
改了东西

// 改进后
fix: 修复首页图片加载闪烁问题

Chrome浏览器下图片懒加载导致布局抖动。
为所有图片添加了width/height属性并改用IntersectionObserver。

Fixes #326

提交消息与版本发布

规范的提交消息可以自动生成变更日志：

# 生成最近版本变更
git log v1.0.0..v1.1.0 --pretty=format:"- %s (%h)" --no-merges

语义化版本(SemVer)依据提交类型决定版本号：

• feat → 次版本(minor)
• fix → 修订版本(patch)
• BREAKING CHANGE → 主版本(major)

历史提交修正

修改上次提交消息：

git commit --amend

交互式变基修改多个提交：

git rebase -i HEAD~3
# 将pick改为reword

企业级实践案例

大型项目提交消息模板：

类型(模块): 简短描述 [JIRA-ID]

详细说明变更背景和影响范围：

- 具体修改点1
- 具体修改点2

测试建议：
1. 测试场景1
2. 测试场景2

关联资料：
- 设计文档链接
- API文档链接

BREAKING CHANGE: 说明不兼容变更

多语言项目处理

非英语团队建议使用双语消息：

fix(login): 修复验证码发送限制问题 [Fix SMS limit]

验证码接口未做频率限制导致被恶意调用。
Added rate limiting (10 requests/hour) to /api/sms.

修复内容：
- 添加Redis计数器
- 返回429状态码
- 记录安全日志

Security: MEDIUM