Git常规提交注释规范定义
Git常规提交注释规范定义
总结
Conventional Commits 规范是建立在提交消息之上的轻量级约定。 它提供了一组简单的规则,用于创建显式提交历史记录; 这使得在它上面编写自动化工具变得更加容易。 此约定与 SemVer 相吻合, 通过描述提交消息中的功能、修复和重大更改。
提交消息的结构应如下:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
提交包含以下结构元素,用于将 intent 传达给 图书馆的使用者:
- fix:该类型的提交会修补代码库中的错误(这与语义版本控制中的 PATCH 相关)。
fix
- feat:该类型的提交为代码库引入了新功能(这与语义版本控制中的 MINOR 相关)。
feat
- 中断性变更:具有页脚或在类型/范围后附加 a 的提交引入了重大 API 变更(与语义版本控制中的 MAJOR 相关)。 中断性变更可以是任何类型的提交的一部分。
BREAKING CHANGE:``!
- 允许的类型,例如 @commitlint/config-conventional (基于 Angular 约定)推荐 、 、 、 、 、 、 等。
fix:``feat:``build:``chore:``ci:``docs:``style:``refactor:``perf:``test:
- 页脚以外的 可能提供,并遵循类似于 Git Trailer 格式的约定。
BREAKING CHANGE: <description>
其他类型不是由常规提交规范强制要求的,并且在语义版本控制中没有隐式效果(除非它们包含中断性变更)。 可以向提交类型提供范围,以提供额外的上下文信息,并包含在括号内,例如.feat(parser): add ability to parse arrays
例子
包含说明和中断性变更页脚的提交消息
feat: allow provided config object to extend other configs
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 页脚提交消息 !
chore!: drop support for Node 6
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
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
规范
本文档中的关键字“必须”、“不得”、“必需”、“应”、“不应”、“应该”、“不应”、“推荐”、“可以”和“可选”应按照 RFC 2119 中的描述进行解释。
- 提交必须以类型为前缀,该类型由名词、、等组成,后跟 按 OPTIONAL 作用域、OPTIONAL 和 REQUIRED 终端冒号和空格。
feat``fix``!
- 当提交将新功能添加到应用程序或库时,必须使用该类型。
feat
- 当提交表示应用程序的错误修复时,必须使用该类型。
fix
- 可以在类型之后提供范围。范围必须由描述的名词组成 用括号括起来的代码库部分,例如,
fix(parser):
- 说明必须紧跟在类型/范围前缀后面的冒号和空格后面。 描述是代码更改的简短摘要,例如, 修复:字符串中包含多个空格时的数组解析问题 。
- 可以在简短描述之后提供更长的提交正文,提供有关代码更改的其他上下文信息。正文必须在描述后以一个空行开头。
- 提交正文是自由格式的,可以由任意数量的换行符分隔的段落组成。
- 可以在正文后提供一个或多个页脚一个空行。每个页脚必须包含以下内容 一个单词标记,后跟 A 或 分隔符,后跟一个字符串值(这是受 Git Trailer 约定的启发)。
:<space>``<space>#
- 页脚的标记必须用于代替空格字符,例如,(这有助于区分 多段落正文中的页脚部分)。例外情况是 ,它也可以用作令牌。
-``Acked-by``BREAKING CHANGE
- 页脚的值可以包含空格和换行符,并且解析必须在下一个有效页脚时终止 观察到标记/分隔符对。
- 中断性变更必须在提交的类型/范围前缀中指示,或作为 页脚。
- 如果包含在页脚中,中断性变更必须包含大写文本 BREAKING CHANGE,后跟冒号、空格和说明,例如 BREAKING CHANGE:环境变量现在优先于配置文件 。
- 如果包含在类型/范围前缀中,则中断性更改必须由 .如果使用,可以从页脚部分省略, 提交描述应用于描述中断性变更。
!``:``!``BREAKING CHANGE:
- 提交消息中可能使用 和 以外的类型,例如 docs: update ref docs。
feat``fix
- 实现者不得将构成常规提交的信息单元视为区分大小写,但 BREAKING CHANGE 除外,它必须为大写。
- 当用作页脚中的标记时,BREAKING-CHANGE 必须与 BREAKING CHANGE 同义。
为什么使用常规提交
- 自动生成更改日志。
- 自动确定语义版本升级(基于登陆的提交类型)。
- 将变更的性质传达给团队成员、公众和其他利益相关者。
- 触发生成和发布过程。
- 通过允许人们探索,使人们更容易为您的项目做出贡献 更有条理的提交历史记录。
常见问题
在初始开发阶段,我应该如何处理提交消息?
我们建议您继续操作,就像您已经发布了产品一样。通常, 有人 ,即使是你的软件开发人员,也在使用你的软件。他们会想知道哪些是固定的,哪些是损坏的,等等。
提交标题中的类型是大写还是小写?
可以使用任何外壳,但最好保持一致。
如果提交符合多种提交类型,我该怎么办?
尽可能返回并进行多次提交。传统提交的部分好处是它能够推动我们进行更有条理的提交和 PR。
这岂不是阻碍了快速开发和快速迭代?
它不鼓励以无序的方式快速移动。它可以帮助您在具有不同贡献者的多个项目中快速、长期地移动。
传统提交是否会导致开发人员限制他们所做的提交类型,因为他们会考虑提供的类型?
常规提交鼓励我们进行更多某些类型的提交,例如修复。除此之外,传统提交的灵活性允许你的团队提出自己的类型,并随着时间的推移改变这些类型。
这与 SemVer 有什么关系?
fix
类型提交应转换为发布。 类型提交应转换为发布。提交中的提交,无论类型如何,都应转换为发行版。PATCH``feat``MINOR``BREAKING CHANGE``MAJOR
我应该如何对常规提交规范的扩展进行版本控制,例如?@jameswomack/conventional-commit-spec
我们建议使用 SemVer 发布你自己的此规范扩展(以及 鼓励您进行这些扩展!
如果我不小心使用了错误的提交类型,我该怎么办?
当您使用的类型符合规范但不是正确的类型时,例如 而不是 fix``feat
在合并或释放错误之前,我们建议使用 编辑提交历史记录。发布后,清理会根据您使用的工具和流程而有所不同。git rebase -i
当您使用不符合规范的类型时,例如 而不是 feet``feat
在最坏的情况下,如果提交不符合常规提交规范,则不是世界末日。它只是意味着基于规范的工具将错过提交。
我的所有贡献者都需要使用常规提交规范吗?
不!如果您在 Git 上使用基于 squash 的工作流,则主要维护者可以在合并提交消息时清理它们,从而不会给临时提交者增加工作量。 一个常见的工作流程是让你的 git 系统自动从拉取请求中压缩提交,并为首席维护者提供一个表单,以便为合并输入正确的 git 提交消息。
传统提交如何处理还原提交?
还原代码可能很复杂:是否要还原多个提交?如果您恢复某个功能,下一个版本是否应该是一个补丁?
常规提交不会明确定义还原行为。相反,我们把它留给工具 作者利用类型和页脚的灵活性来开发处理还原的逻辑。
一个建议是使用类型和引用要还原的提交 SHA 的页脚:revert
revert: let us never again speak of the noodle incident
Refs: 676104e, a215868