ShinKouyo 的 Git 提交规范 版本 1.2, 2026-07 Copyright (C) 2026 ShinKouyo This document is licensed under CC BY-SA 4.0. To view a copy of this license, visit https://creativecommons.org/licenses/by-sa/4.0/ 此文档基于 Conventional Commits 规范修改, 两者之间存在差异. 1. 概述 本规范定义了一套 Git 提交信息的编写约定, 旨在创建清晰可读的提交历史, 同时便于自动化工具处理. 提交信息中的所有文本必须使用英文编写. 提交信息的格式如下: <类型>[可选 范围][可选 状态标记]: <描述> [可选 正文] [可选 脚注] 各字段含义: - 类型 (type): 一个名词, 说明提交的性质. 必须存在. - 范围 (scope): 用圆括号括起的名词, 指明变更影响的模块或组件. 可选. - 状态标记: 紧接在类型 (及可选范围) 之后, 冒号之前. - ! : 破坏性变更 (breaking change) - ~ : 工作进行中 (WIP), 表示提交尚未完成 - 描述 (description): 变更的简短总结. 紧跟冒号和空格, 必须存在. - 正文 (body): 提供额外上下文的详细说明. 可选. - 脚注 (footer): 包含结构化元数据 (如引用, 评审人). 可选. 2. 术语 本文中的关键词 "必须 (MUST)", "禁止 (MUST NOT)", "必要 (REQUIRED)", "应当 (SHALL)", "不应当 (SHALL NOT)", "应该 (SHOULD)", "不应该 (SHOULD NOT)", "推荐 (RECOMMENDED)", "可以 (MAY)" 和 "可选 (OPTIONAL)" 的解释参考 RFC 2119 (https://www.ietf.org/rfc/rfc2119.txt). 3. 规范 3.1. 类型 (type) 类型是一个名词, 用于说明提交的性质. 每个提交必须包含一个类型字段, 后可接可选的圆括号范围和可选的状态标记. 推荐使用以下类型: - feat: 新增功能 - fix: 修复 bug - build: 修改构建系统或外部依赖 - chore: 修改非业务代码 - ci: 修改持续集成配置 - conf: 修改配置文件 - deps: 添加, 更新或移除依赖项 - docs: 仅文档变更 - style: 代码格式调整 - refactor: 代码重构 - perf: 性能优化 - test: 添加或修改测试 - revert: 还原之前的提交 - sec: 修复安全漏洞 - lint: 修复 linter 警告或添加 lint 规则 - merge: 合并分支 - release: 发布新版本 - i18n: 国际化或本地化相关变更 - a11y: 可访问性改进 - init: 初始化项目或模块 除上述类型外, 项目可以根据需要自由扩展其他类型. 3.2. 范围 (scope) 范围是一个可选的圆括号字段, 紧跟在类型之后, 用于指明变更影响的模块或 组件. 如果存在范围, 必须用圆括号包围, 且其内容应该是描述代码模块或子系统的 名词. 例如: feat(parser): add error recovery. 3.3. 状态标记 (marker) 状态标记是可选的, 紧跟在类型 (及可选范围) 之后, 直接置于冒号之前. 支持以下标记: - ! : 表示该提交引入了破坏性变更 (breaking change). - ~ : 表示该提交尚未完成 (WIP), 属于临时保存的中间状态, 不应纳入正式发布. 标记 ! 是表示破坏性变更的唯一正式方式. 引入破坏性变更的提交必须使用 ! 标记, 且该标记必须紧接在冒号之前. WIP 提交必须使用 ~ 标记. 它可以与 ! 组合使用, 此时顺序必须为 !~. 如果使用了 ! 标记, 可以在脚注中使用 "BREAKING CHANGE: <说明>" 补充 更详细的破坏性说明, 但该脚注不能替代 ! 标记. 3.4. 描述 (description) 描述是对变更的简短总结. 它必须直接跟在冒号和空格之后, 并且必须位于 同一行内. 描述应该以动词开头, 首字母小写, 末尾不应该有句号. 3.5. 正文 (body) 正文是可选的, 用于提供额外上下文. 如果存在正文, 必须从描述后的空行开始. 正文可以自由格式, 允许使用空行 分段. 3.6. 脚注 (footer) 脚注是可选的, 位于正文之后 (以一个空行分隔). 它可以包含一行或多行. 每行脚注必须包含一个令牌 (token), 后跟 ": " 或 " #" 作为分隔符, 再跟 具体值. 令牌必须使用连字符 (如 Acked-by), 且必须首字母大写, 但 "BREAKING CHANGE" 例外 —— 它必须全部大写. 推荐使用的脚注令牌: - Refs: 引用相关的 Issue, PR 或提交哈希 - Closes: 关闭某个 Issue 或 PR - Fixes: 修复某个 issue - Reviewed-by: 标注评审人 - Co-authored-by: 标注共同作者 - Signed-off-by: 标注签署人, 表示提交者签署该提交. 格式为 姓名 <邮箱>. - See-also: 相关的其他资源或链接 - Co-Developed-By: 标注共同开发者 (含 LLM 工具). 见 3.9. - Assisted-by: 标注辅助工具或 LLM 模型. 见 3.9. 3.7. revert 类型 还原提交必须使用 revert 类型. 应该在脚注中引用被还原的提交哈希, 建议使用 Refs: 或 Closes: 等令牌. 3.8. 工具实现 工具实现必须不区分大小写地解析类型和范围, 但 ! 和 ~ 标记必须严格区分, 且 "BREAKING CHANGE" 令牌必须大写. 3.9. LLM 注明 当 LLM 工具参与提交内容的生成时, 提交信息必须注明所使用的工具或模型. 以下两种方式至少使用一种: 3.9.1. Co-Authored-By 或 Co-Developed-By (推荐) 在脚注中注明所使用的 LLM 工具, 格式为 "Co-Authored-By: <工具标识>" 或 "Co-Developed-By: <工具标识>". 工具标识可以是以下形式之一: 仅名称, 名称 <邮箱地址>, 或名称 <网址>. 3.9.2. Assisted-by 在脚注中注明所使用的 LLM 模型, 格式为 "Assisted-by: [组织:]模型 [可选 补充说明]". 组织前缀可选, 补充说明 (如果存在) 由空格分隔. 4. 示例 4.1. 破坏性变更 feat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. 4.2. 破坏性变更 + WIP feat!~: partial implementation of new API 4.3. WIP 提交 feat~: start implementing new dashboard 4.4. 常规修复 fix: correct spelling in error message 4.5. 带模块范围的新功能 feat(lang): add polish language 4.6. 初始化 init: setup project structure 4.7. 多行正文和脚注 fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 4.8. 还原提交 revert: let us never again speak of the noodle incident Refs: 676104e, a215868 4.9. LLM 注明 (Co-Authored-By) feat: add user authentication Co-Authored-By: ExampleTool 4.10. LLM 注明 (Co-Developed-By) fix: resolve race condition in scheduler Co-Developed-By: ExampleTool