提交规范

一句话版

代码、注释、文档、提交信息统一中文；格式遵循 conventional-commit：type(scope): 主题，其中 type 与 scope 保持小写英文。

为什么主题写中文，type 却留英文

一条提交里这两半的读者不是同一个。主题写给人看，维护这个仓库的是中文团队，用母语说清改动动机比用英文更准。type 和 scope 写给机器看，生成 release note、判定语义化版本的工具按一张固定词表解析它，换成中文就解析不了。两种语言各司其职，不是没统一。

格式

type(scope): 主题

[可选的正文,说明动机/影响,而不是复述 diff]

• type：固定词表，见下方。
• scope：可选，标注改动影响的范围（模块名、包名、目录名）。跨领域或没有明确单一范围的改动可以省略。
• 主题：一句话说清做了什么，不加句号。

type 取值

从仓库真实提交历史提炼，新增提交按语义就近选用，不要自造新词：

type	用于
feat	新功能
fix	修复缺陷
docs	仅文档改动（README、设计文档、注释翻译等）
refactor	不改变外部行为的内部重构
test	新增或调整测试
build	构建产物、打包元数据相关（如模板包图标/README）
ci	CI/CD 流水线、发版流程
chore	维护性杂务：依赖升级、忽略规则、重新生成产物，不影响功能与外部行为

例子

fix(web,backend): 每个操作按钮都挂上按钮级权限
fix(web): 无权限用户的按钮不再渲染
feat: 演示模式,展示部署下拦截所有写操作
feat(notice): 定向投递 + 通知铃富文本
feat(menu): 应用级权限路由选择器 + 菜单交互清理
refactor(web): 把重复的分页映射收敛成两个 helper
test: 补齐未覆盖服务区域的 CRUD 与端点用例
build(templates): 模板包补上图标与 readme
ci(release): 修发布流水线里的变量名笔误
docs: README 双语对齐 zh-CN 基线

要点：

• scope 可以是单个模块（web、notice、menu），也可以逗号并列多个（web,backend）。改动确实横跨两侧时就如实标注，不必强行归到一个。
• 没有明确单一范围、或改动本身就是全局性的（比如整仓文档翻译、新增一个横切能力），省略 scope，直接 type: 主题。
• 主题 允许用 —/:/括号做简短的补充说明，但整体仍是一句话，不要写成多句复合句。

正文（body）什么时候要写

一行 主题 说不清楚改动的动机或影响面时才加正文，例如：

• 修的是一个隐蔽的安全问题，需要说明触发条件和影响范围。
• 一次改动牵涉多处协同（前后端字段改名、配置迁移），需要给后来者一份「为什么这么改」的说明。

正文不是用来复述 diff 的，diff 本身就能看到改了什么代码。它补的是 diff 里看不出来的背景。日常的小修小补不需要正文，一行 主题 足够，比如样式调整、单个 bug 修复。

常见误区

不要做的事

• 主题 结尾加句号。
• 把 type 或 scope 也写成中文（那半是给工具解析的，词表固定）。
• 把多个不相关的改动塞进一个 commit，再用一个笼统的 type 概括（比如同时改了 feat 的功能和 fix 的缺陷）。应按语义拆成多个提交。
• type 用仓库历史里没出现过的自造词（如 update、change）。语义已经被 feat/fix/refactor 等覆盖，新造词只会让历史不一致。