提交信息规范
在为该项目创建代码提交时,请遵循以下规范。
前置要求
提交代码前,请确保你在功能分支上开发,而非主分支。
bash
# 检查当前分支 git branch --show-current
若当前处于 main 、 master 或 dev 分支, 先创建新分支:
bash
# 创建并切换到新分支 git checkout -b <type>/<short-description>
分支命名应该遵循 <type>/<short-description> 格式,其中的类型需与提交类型保持一致 (例如: feat/add-user-auth, fix/null-pointer-error, ref/extract-validation).
提交信息格式
code
<提交类型>(<作用域>): <主题> <正文主体> <脚注>
信息头是必须的但作用域可选,所有行的字符长度不得超过 300 个字符, 主题、正文主体尽量采用中文描述。
提交类型说明
| 类型 | 用途 |
|---|---|
feat | 新特性 |
fix | 问题修复 |
ref | 代码重构(不涉及功能逻辑变更) |
perf | 性能优化 |
docs | 文档变更 |
test | 添加或修正测试代码 |
build | 构建系统或依赖包调整 |
ci | 持续集成配置 |
chore | 日常维护任务 |
style | 代码格式化(无逻辑变更) |
meta | 仓库元信息调整 |
license | License变更 |
主题规则说明
- •末尾不用加句号
- •最大120个字符
正文主体编写指南
- •说明 做了什么 和 为什么做, 不要描述具体实现
- •使用祈使句
- •写明变更的动机
- •必要时对比变更前后的差异
脚注: Issue References
Reference issues in the footer using these patterns:
code
Fixes TSF2601211926368681 Refs LINEAR-ABC-123
- •
Fixes关联对应bug编号(灵畿平台) - •
Refslinks without closing
AI 生成代码的提交规范
当代码变更主要由代码生成工具(如 Trea, Claude Code, Codebuddy)完成时,需在提交脚注中添加联合作者声明:
code
联合作者: Trae / Claude / Codebuddy
这是提交信息中唯一允许体现 AI 参与的方式。禁止在主题、正文或其他位置添加类似表述。
举例说明
简单bug修复
code
fix(api): 处理用户接口的响应为空的问题 当用户账号被删除时,用户接口会返回空值,导致前端展现异常。 在访问用户属性前增加空值校验逻辑。 Fixes SENTRY-5678 联合作者: Trae
新特性开发
code
feat(alerts): 增加一个用户高风险操作的报警功能 当用户进行高风险操作的时候发起报警. Refs GH-1234
代码重构
code
ref: 将通用的验证逻辑提取到共享模块中。 将三个入口的重复验证代码移至一个共享验证器类中。无行为变更。
带有破坏性的变更
code
feat(api)!: 删除重复的v1入口 删除所有在 V23.1 版本中已弃用的 v1 API 入口。客户端应迁移至 v2 入口。 破坏性变更点: v1 入口未来不再可用 Fixes SENTRY-9999
回滚
code
revert: feat(api): 添加新的端点 将撤销提交 ID: abc123def456. 原因:在生产环境中导致了性能退化。
原则
- •每个提交应对应一个独立、稳定的变更。
- •提交内容需具备独立可评审性。
- •每次提交后,代码仓库需处于可正常运行的状态。