代码提交规范

Conventional Commits

约定式提交规范是一种基于提交信息的轻量级约定。 它提供了一组简单规则来创建清晰的提交历史； 自动化生成 CHANGELOG。这更有利于编写自动化工具。 通过在提交信息中描述功能、修复和破坏性变更， 使这种惯例与 SemVer 相互对应。

提交说明的结构如下所示：

原文：

1
2
3
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]

译文：

1
2
3
<类型>[可选 范围]: <描述>
[可选 正文]
[可选 脚注]

<类型>[可选 范围]:（一个空格）<描述>（多个提交内容以分号分割）

提交类型

提交类型 标题 描述 表情符号 发布 包含在变更日志中
feat 特征 一个新功能 ✨ minor true
fix Bug修复 一个错误修复 🐛 patch true
docs 文档 仅文档更改 📚 patch如果scope是readme true
style 风格 不影响代码含义的更改（空格、格式、缺少分号等） 💎 - true
refactor 代码重构 既不修复错误也不添加功能的代码更改 📦 - true
perf 性能改进 提高性能的代码更改 🚀 patch true
test 测试 添加缺失的测试或纠正现有测试 🚨 - true
build 构建 影响构建系统或外部依赖项的更改（示例范围：gulp、broccoli、npm） 🛠 patch true
ci 持续集成 对 CI 配置文件和脚本的更改（示例范围：Travis、Circle、BrowserStack、SauceLabs） ⚙️ - true
chore 家务活 其他不修改 src 或测试文件的更改 ♻️ - true
revert 恢复 恢复之前的提交 🗑 - true

提交别名

别名允许拥有额外的提交类型（例如在commitizen等工具中），这些提交类型可以被格式化以遵循AngularJS 提交消息约定。

例如，commitizen CLI 可以提供选择initial，最终提交消息将是“feat：初始提交🎉”

提交类型 映射到 标题 描述 表情符号
initial feat 最初的 初始提交 🎉
dependencies fix 依赖关系 更新依赖项 ⬆️
peerDependencies fix 对等依赖 更新对等依赖关系 ⬆️
devDependencies chore 开发依赖 更新开发依赖 ⬆️
metadata fix 元数据 更新元数据 (package.json) 📦

约定式提交规范

  1. 每个提交都必须使用类型字段前缀，它由一个名词构成，诸如 feat 或 fix ， 其后接可选的范围字段，可选的 !，以及必要的冒号（英文半角）和空格。
  2. 当一个提交为应用或类库实现了新功能时，必须使用 feat 类型。
  3. 当一个提交为应用修复了 bug 时，必须使用 fix 类型。
  4. 范围字段可以跟随在类型字段后面。范围必须是一个描述某部分代码的名词，并用圆括号包围，例如： fix(parser):
  5. 描述字段必须直接跟在 <类型>(范围) 前缀的冒号和空格之后。 描述指的是对代码变更的简短总结，例如： fix: array parsing issue when multiple spaces were contained in string 。
  6. 在简短描述之后，可以编写较长的提交正文，为代码变更提供额外的上下文信息。正文必须起始于描述字段结束的一个空行后。
  7. 提交的正文内容自由编写，并可以使用空行分隔不同段落。
  8. 在正文结束的一个空行之后，可以编写一行或多行脚注。每行脚注都必须包含 一个令牌（token），后面紧跟 :<space> 或 <space># 作为分隔符，后面再紧跟令牌的值（受 git trailer convention 启发）。
  9. 脚注的令牌必须使用 - 作为连字符，比如 Acked-by (这样有助于 区分脚注和多行正文)。有一种例外情况就是 BREAKING CHANGE，它可以被认为是一个令牌。
  10. 脚注的值可以包含空格和换行，值的解析过程必须直到下一个脚注的令牌/分隔符出现为止。
  11. 破坏性变更必须在提交信息中标记出来，要么在 <类型>(范围) 前缀中标记，要么作为脚注的一项。
  12. 包含在脚注中时，破坏性变更必须包含大写的文本 BREAKING CHANGE，后面紧跟着冒号、空格，然后是描述，例如： BREAKING CHANGE: environment variables now take precedence over config files 。
  13. 包含在 <类型>(范围) 前缀时，破坏性变更必须通过把 ! 直接放在 : 前面标记出来。 如果使用了 !，那么脚注中可以不写 BREAKING CHANGE:， 同时提交信息的描述中应该用来描述破坏性变更。
  14. 在提交说明中，可以使用 feat 和 fix 之外的类型，比如：docs: updated ref docs. 。
  15. 工具的实现必须不区分大小写地解析构成约定式提交的信息单元，只有 BREAKING CHANGE 必须是大写的。
  16. BREAKING-CHANGE作为脚注的令牌时必须是 BREAKING CHANGE 的同义词。

示例

  1. 包含了描述并且脚注中有破坏性变更的提交说明
1
2
3
feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files
  1. 包含了 ! 字符以提醒注意破坏性变更的提交说明
1
feat!: send an email to the customer when a product is shipped
  1. 包含了范围和破坏性变更 ! 的提交說明
1
feat(api)!: send an email to the customer when a product is shipped
  1. 包含了 ! 和 BREAKING CHANGE 脚注的提交说明
1
2
3
chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.
  1. 不包含正文的提交说明
1
docs: correct spelling of CHANGELOG
  1. 包含范围的提交说明
1
feat(lang): add polish language
  1. 包含多行正文和多行脚注的提交说明
1
2
3
4
5
6
7
8
9
10
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

分支名规范

对于个人开发版本：

分支名格式：

你的姓名/特性关键字/分支内容名（第一个字母小写，多个单词使用驼峰式）

新功能：

1
2
3
4
yourName/feat/branchName

例如
zhangsan/feat/supportHttpLib

修复bug

1
2
3
4
yourName/fix/branchName

例如
zhangsan/fix/fixSelectServiceTime

发版的版本可以继续沿用1.2.0这种格式。

特性关键字说明：

1
2
3
4
5
6
7
//既有feat，又有fix或者其他使用feat
feat: 功能或者特性修改
fix: 修复bug
chore：非功能性修改，例如修正代码风格、修正错别字、重命名变量等
docs:文档性更新
test：增加测试。
merge：代码合并。

其他手册

约定式提交官网：https://www.conventionalcommits.org/zh-hans/

完整提交类型列表：https://github.com/pvdlg/conventional-changelog-metahub#commit-types

自动生成 CHANGELOG GitHub Action：https://github.com/marketplace/actions/changelog-from-conventional-commits

Conventional Changelog：https://github.com/conventional-changelog/standard-version