常规提交

2020-08-20 03:10:46

传统的提交规范是在提交消息之上的一个轻量级约定。它提供了一组用于创建显式提交历史的简单规则;这使得在上面编写自动化工具变得更容易。通过描述提交消息中的功能、修复和破坏更改,该约定与SemVer相吻合。

提交包含以下结构元素,以便向库的消费者传达意图:

FIX:类型FIX的提交修补了代码库中的错误(这与语义版本控制中的补丁相关)。

Feat:类型Feat的提交为代码库引入了一个新功能(这与语义版本控制中的次要相关)。

中断更改:具有页脚中断更改的提交:,或附加!在类型/作用域之后,引入一个突破性的API变更(与语义版本控制中的主要相关)。突破性变更可以是任何类型的提交的一部分。

除FIX:和FEAT:之外的类型都是允许的,例如@COMMITLINT/CONFIG-CONVANCENT(基于角度约定)建议build:、chore:、ci:、docs:、style:、refactor:、perf:、test:等。

可以提供除中断更改以外的页脚:<;Description>;,并遵循类似于GIT尾部格式的约定。

附加类型不受传统提交规范的强制要求,并且在语义版本控制中没有隐含效果(除非它们包含突破性更改)。作用域可以提供给提交的类型,以提供附加的上下文信息,并包含在括号中,例如,Feat(解析器):添加解析数组的能力。

Feat:允许提供的配置对象扩展其他配置BREAKING更改:配置文件中的`extends`键现在用于扩展其他配置文件。

重构!:取消对Node 6BREAKING的支持BREAKING更改:重构以使用Node6中没有的JavaScript功能。

本文档中的关键字“必须”、“不得”、“必需”、“必须”、“不得”、“应该”、“不应该”、“推荐”、“可能”和“可选”应按照RFC 2119中的说明进行解释。

COMMITS必须以类型为前缀,该类型由名词、特征、修复等组成,后跟可选范围、可选!以及所需的末尾冒号和空格。

当提交将新功能添加到应用程序或库中时,必须使用类型特性。

当提交表示应用程序的错误修复时,必须使用类型修复。

可以在类型之后提供作用域。作用域必须由描述用括号括起来的代码库的部分的名词组成,例如,fix(解析器):

说明必须紧跟在类型/范围前缀后面的冒号和空格之后。说明是代码更改的简短摘要,例如,FIX:字符串中包含多个空格时的数组解析问题。

可以在简短描述之后提供更长的提交主体,以提供关于代码改变的附加上下文信息。正文必须在描述后开始一个空行。

提交正文是自由格式的,可以由任意数量的换行符分隔的段落组成。

可以在正文之后提供一个或多个页脚一个空行。每个页脚必须包含一个单词标记,后跟一个:<;空格>;或<;空格>;#分隔符,然后是一个字符串值(这受到git尾部约定的启发)。

页脚标记必须使用-来代替空格字符,例如Acked-by(这有助于将页脚部分与多段落正文区分开来)。破损找零是一个例外,它也可以用作令牌。

脚注的值可以包含空格和换行符,当观察到下一个有效的脚注标记/分隔符对时,解析必须终止。

中断更改必须在提交的类型/范围前缀中指示,或者作为页脚中的条目指示。

如果包含在页脚中,则中断更改必须由大写文本中断更改,后跟冒号、空格和描述组成,例如中断更改:环境变量现在优先于配置文件。

如果包括在类型/作用域前缀中,中断更改必须用!紧接在:之前。如果!在页脚部分可以省略,提交描述将用来描述中断更改。?

除了FEAT和FIX之外的类型可以在您的提交消息中使用,例如,docs:update ref docs。

除了必须大写的中断更改外,实现者不能将组成常规提交的信息单元视为区分大小写。

在页脚中用作标记时,中断更改必须与中断更改同义。

通过允许人们利用更结构化的提交历史,使他们更容易为您的项目做出贡献。

我们建议您继续操作,就像您已经发布了产品一样。通常会有人,即使是您的软件开发人员同事,也在使用您的软件。他们会想知道什么修好了,什么坏了等等。

如果提交符合多个提交类型,我该怎么办?

只要有可能,就回去进行多次提交。传统提交的部分好处是它能够驱使我们进行更有组织的提交和公关。

它不鼓励以杂乱无章的方式快速移动。它可以帮助您在具有不同贡献者的多个项目中快速、长期地移动。

常规提交是否会导致开发人员限制他们提交的类型,因为他们会考虑提供的类型?

常规提交鼓励我们进行更多的某些类型的提交,例如修复。除此之外,常规提交的灵活性允许您的团队提出自己的类型,并随着时间的推移更改这些类型。

修复类型提交应该转换为补丁版本。Feat类型提交应转换为次要版本。提交中有破坏性更改的提交,无论是哪种类型,都应该转换为主要版本。

我们推荐使用SemVer发布您自己对此规范的扩展(并鼓励您进行这些扩展!)。

当您使用符合规范但不是正确类型的类型时,例如,FIX而不是FEAT。

在合并或释放错误之前,我们建议使用git rebase-i编辑提交历史记录。发布后,根据您使用的工具和过程的不同,清理会有所不同。

在最坏的情况下,如果提交不符合常规的提交规范,这并不是世界末日。这仅仅意味着基于规范的工具将错过提交。

不!如果您在Git上使用基于挤压的工作流,那么主管维护人员可以在合并时清理提交消息-不会向临时提交者添加任何工作负载。为此,常见的工作流程是让您的Git系统自动挤压来自拉请求的提交,并为主管维护人员提供一个表单,以便为合并输入适当的GIT提交消息。

还原代码可能很复杂:是否要还原多个提交?如果您恢复了一个功能,那么下一个版本是否应该改为补丁?

常规提交不会显式地定义还原行为。相反,我们让工具作者使用类型和页脚的灵活性来开发他们处理还原的逻辑。

一种建议是使用还原类型和引用要还原的提交SHA的页脚:

传统的提交规范受到角度提交准则的启发,并在很大程度上基于该准则。

本规范的第一稿是与一些参与以下工作的人员合作编写的:

Bumping:一种用于发布软件的工具,使您可以在发布新版本的软件之前和之后轻松执行操作。

Commitien-Tools/Commitisen:一个用Python编写的工具,用于创建项目提交规则、自动跳转版本和自动更改日志生成。

PHP-Commitisen:一个PHP工具,构建用于创建遵循常规提交规范的提交消息。可配置并可用于PHP项目,作为编写器依赖项,或可全局用于非PHP项目。

Gitlint:Git Commit message Linter是用Python编写的,可以配置为强制执行传统的提交格式。

Conform:可用于对git存储库实施策略的工具,包括常规提交。

Git-Commits-Self:获取自Period以来的所有(原始)提交,或者(默认情况下)从最新的git SemVer标记获取所有提交,外加插件支持。

Standard-Version:使用GitHub的新挤压按钮和推荐的常规提交工作流,自动进行版本控制和更改日志管理。

常规提交:为VCS提交对话框内的常规提交提供可扩展的上下文和基于模板的完成和检查。适用于所有JetBrains IDE。

Git提交模板:向JetBrains编辑器添加常规提交支持(IntelliJ IDEA、PyCharm、PhpStorm…)。。

Commitsar:用于检查分支上的提交是否符合常规提交的GO工具。附带Docker映像,供CI使用。

语义发布:一个自动化整个包发布工作流程的工具,包括:确定下一个版本号、生成发布说明和发布包。

Python-语义-发布:Python项目的自动语义版本控制。这是Node.js语义版本的Python实现。

Pyhist:一个Python实用程序,用于根据git历史自动更新包版本并生成ChangeLog。

Istanbuljs:用于向JavaScript测试添加测试覆盖率的开源工具和库的集合。

NINTEX表单:轻松创建动态在线表单,以捕获和提交准确的最新数据。

Uno平台:用C#和XAML构建移动、桌面和WebAssembly应用。今天。开源并得到专业支持。