跳至主要內容

【规范】约定式提交 1.0.0

Chihiro.Star大约 9 分钟

【规范】约定式提交 1.0.0

📔 千寻简笔记介绍

千寻简文库已开源,Gitee与GitHub搜索chihiro-doc,包含笔记源文件.md,以及PDF版本方便阅读,文库采用精美主题,阅读体验更佳,如果文章对你有帮助请帮我点一个Star

更新:支持在线阅读文章,根据发布日期分类。

@[toc]

1 概述

1.1 约定式提交规范

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

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

  • 原文:
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
  • 译文:
<类型>[可选 范围]: <描述>

[可选 正文]

[可选 脚注]

1.2 提交说明

提交说明包含了下面的结构化元素,以向类库使用者表明其意图:

  1. fix: 类型fix 的提交表示在代码库中修复了一个 bug(这和语义化版本中的 PATCHopen in new window 相对应)。
  2. feat: 类型feat 的提交表示在代码库中新增了一个功能(这和语义化版本中的 MINORopen in new window 相对应)。
  3. BREAKING CHANGE: 在脚注中包含 BREAKING CHANGE: 或 <类型>(范围) 后面有一个 ! 的提交,表示引入了破坏性 API 变更(这和语义化版本中的 MAJORopen in new window 相对应)。 破坏性变更可以是任意 类型 提交的一部分。
  4. fix:feat: 之外,也可以使用其它提交 类型 ,例如 @commitlint/config-conventionalopen in new window(基于 Angular 约定open in new window)中推荐的 build:chore:ci:docs:style:refactor:perf:test:,等等。
  5. 脚注中除了 BREAKING CHANGE: <description> ,其它条目应该采用类似 git trailer formatopen in new window 这样的惯例。

其它提交类型在约定式提交规范中并没有强制限制,并且在语义化版本中没有隐式影响(除非它们包含 BREAKING CHANGE)。 可以为提交类型添加一个围在圆括号内的范围,以为其提供额外的上下文信息。例如 feat(parser): adds ability to parse arrays.

2 示例

  • 包含了描述并且脚注中有破坏性变更的提交说明
# 允许提供的配置对象扩展其他配置
feat: allow provided config object to extend other configs
# 配置文件中的“extends”键现在用于扩展其他配置文件
BREAKING CHANGE: `extends` key in config file is now used for extending other config files
  • 包含了 ! 字符以提醒注意破坏性变更的提交说明
# 在产品发货时向客户发送电子邮件
feat!: send an email to the customer when a product is shipped
  • 包含了范围和破坏性变更 ! 的提交說明
# 在产品发货时向客户发送电子邮件
feat(api)!: send an email to the customer when a product is shipped
  • 包含了 ! 和 BREAKING CHANGE 脚注的提交说明
# 节点6的丢弃支持
chore!: drop support for Node 6
# 突破性变更:使用节点6中不可用的JavaScript功能。
BREAKING CHANGE: use JavaScript features not available in Node 6.
  • 不包含正文的提交说明
# 更正变更日志的拼写
docs: correct spelling of CHANGELOG
  • 包含范围的提交说明
# 添加波兰语
feat(lang): add polish language
  • 包含多行正文和多行脚注的提交说明
# 防止请求竞争
fix: prevent racing of requests

# 引入一个请求id和对最新请求的引用。解除来自最新请求以外的传入响应。
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.

# 审核人:Z
Reviewed-by: Z
# 参考编号:#123
Refs: #123

3 *约定式提交规范

3.1 关键词

  • 本文中的关键词
    • “必须(MUST)”
    • “禁止(MUST NOT)”
    • “必要(REQUIRED)”
    • “应当(SHALL)”
    • “不应当(SHALL NOT)”
    • “应该(SHOULD)”
    • “不应该(SHOULD NOT)”
    • “推荐(RECOMMENDED)”
    • “可以(MAY)”
    • “可选(OPTIONAL)”
    • 其相关解释参考 RFC 2119open in new window

3.2 注意

  1. 每个提交都必须使用类型字段前缀,它由一个名词构成,诸如 featfix , 其后接可选的范围字段,可选的 !,以及必要的冒号(英文半角)和空格。
  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 conventionopen in new window 启发)。
  9. 脚注的令牌必须使用 - 作为连字符,比如 Acked-by (这样有助于 区分脚注和多行正文)。有一种例外情况就是 BREAKING CHANGE,它可以被认为是一个令牌。
  10. 脚注的值可以包含空格和换行,值的解析过程必须直到下一个脚注的令牌/分隔符出现为止。
  11. 破坏性变更必须在提交信息中标记出来,要么在 <类型>(范围) 前缀中标记,要么作为脚注的一项。
  12. 包含在脚注中时,破坏性变更必须包含大写的文本 BREAKING CHANGE,后面紧跟着冒号、空格,然后是描述,例如: BREAKING CHANGE: environment variables now take precedence over config files
  13. 包含在 <类型>(范围) 前缀时,破坏性变更必须通过把 ! 直接放在 : 前面标记出来。 如果使用了 !,那么脚注中可以不写 BREAKING CHANGE:, 同时提交信息的描述中应该用来描述破坏性变更。
  14. 在提交说明中,可以使用 featfix 之外的类型,比如:docs: updated ref docs.
  15. 工具的实现必须不区分大小写地解析构成约定式提交的信息单元,只有 BREAKING CHANGE 必须是大写的。
  16. BREAKING-CHANGE 作为脚注的令牌时必须是 BREAKING CHANGE 的同义词。

4 为什么使用约定式提交

  1. 自动化生成 CHANGELOG。
  2. 基于提交的类型,自动决定语义化的版本变更。
  3. 向同事、公众与其他利益关系者传达变化的性质。
  4. 触发构建和部署流程。
  5. 让人们探索一个更加结构化的提交历史,以便降低对你的项目做出贡献的难度。

5 FAQ

5.1 问题及建议

5.1.1 在初始开发阶段我该如何处理提交说明?

  • 我们建议你按照假设你已发布了产品那样来处理。因为通常总 有人 使用你的软件,即便那是你软件开发的同事们。他们会希望知道诸如修复了什么、哪里不兼容等信息。

5.1.2 提交标题中的类型是大写还是小写?

  • 大小写都可以,但最好是一致的。

5.1.3 如果提交符合多种类型我该如何操作?

  • 回退并尽可能创建多次提交。约定式提交的好处之一是能够促使我们做出更有组织的提交和 PR。

5.1.4 这不会阻碍快速开发和迭代吗?

  • 它阻碍的是以杂乱无章的方式快速前进。它助你能在横跨多个项目以及和多个贡献者协作时长期地快速演进。

5.1.5 约定式提交会让开发者受限于提交的类型吗(因为他们会想着已提供的类型)?

  • 约定式提交鼓励我们更多地使用某些类型的提交,比如 fixes。除此之外,约定式提交的灵活性也允许你的团队使用自己的类型,并随着时间的推移更改这些类型。

5.1.6 这和 SemVer 有什么关联呢?

  • fix 类型提交应当对应到 PATCH 版本。feat 类型提交应该对应到 MINOR 版本。带有 BREAKING CHANGE 的提交不管类型如何,都应该对应到 MAJOR 版本。

5.1.7 我对约定式提交做了形如 @jameswomack/conventional-commit-spec 的扩展,该如何版本化管理这些扩展呢?

  • 我们推荐使用 SemVer 来发布你对于这个规范的扩展(并鼓励你创建这些扩展!)

5.1.8 如果我不小心使用了错误的提交类型,该怎么办呢?

  • 当你使用了在规范中但错误的类型时,例如将 feat 写成了 fix

  • 在合并或发布这个错误之前,我们建议使用 git rebase -i 来编辑提交历史。

  • 而在发布之后,根据你使用的工具和流程不同,会有不同的清理方案。

5.1.9 当使用了 不在 规范中的类型时,例如将 feat 写成了 feet

  • 在最坏的场景下,即便提交没有满足约定式提交的规范,也不会是世界末日。这只意味着这个提交会被基于规范的工具错过而已。

5.1.10 所有的贡献者都需要使用约定式提交规范吗?

  • 并不!如果你使用基于 squash 的 Git 工作流,主管维护者可以在合并时清理提交信息——这不会对普通提交者产生额外的负担。 有种常见的工作流是让 git 系统自动从 pull request 中 squash 出提交,并向主管维护者提供一份表单,用以在合并时输入合适的 git 提交信息。

5.1.11 约定式提交规范中如何处理还原(revert)提交?

  • 还原提交(Reverting)会比较复杂:你还原的是多个提交吗?如果你还原了一个功能模块,下次发布的应该是补丁吗?

  • 约定式提交不能明确的定义还原行为。所以我们把这个问题留给工具开发者, 基于 类型脚注 的灵活性来开发他们自己的还原处理逻辑。

  • 一种建议是使用 revert 类型,和一个指向被还原提交摘要的脚注:

# 我们不要再提面条事件
revert: let us never again speak of the noodle incident
# 参考编号:676104e,a215868
Refs: 676104e, a215868