Conventional提交规范

Conventional Commits(约定式提交)脱胎于Angular提交信息准则，提供了更加通用、简洁和灵活的提交规范

提交格式如下：

<类型>[可选的作用域]: <描述>
# 空一行
[可选的正文]
# 空一行
[可选的脚注]

页眉设置

强制支持的类型名是fix和feat，同样支持Angular准则中推荐的其他类型

常规提交规范还推荐使用类型improvement，表示在不添加新功能或修复bug的情况下改进当前的实现

页尾设置

强制支持在页脚使用BREAKING CHANGES

提交规范

结合RFC2019，在下面规范中使用关键字来指示需求级别

  • MUST（必须）
  • MUST NOT（禁止）
  • REQUIRED（需要）
  • SHALL（应当）
  • SHALL NOT（不应当）
  • SHOULD（应该）
  • SHOULD NOT（不应该）
  • RECOMMENDED（推荐）
  • MAY（可以）

  • OPTIONAL（可选）

  • 每次提交必须添加类型名为前缀。类型名是一个名词，比如feat、fix，后跟冒号和一个空格

  • 类型feat必须在提交新特征时使用
  • 类型fix必须用于修复bug的提交
  • 类型后面可以添加一个可选的作用域。作用域名是一个短语，表示代码库中的一个小节，比如fix(parser)
  • 在类型/作用域前缀后面必须跟上一个简短描述，关于本次提交的代码修改，比如fix: 字符串中包含多个空格时的数组分析问题
  • 可以在描述后面添加一个长的正文，用于提供额外的上下文信息。正文内容必须在短描述后空一行开始
  • 可以在正文后空一行开始页脚，页脚应该包含这次代码修改的相关问题，比如Fixes #13
  • 不兼容修改(breaking change)必须放置在提交的页脚或正文部分的最开始处，必须使用大写文本BREAKING CHANGE作为前缀，后跟冒号和一个空格
  • 在BREAKING CHANGE:后面必须提供一个描述，关于API的修改，比如BREAKING CHANGE: 环境变量目前优先于配置文件
  • 页脚必须包含不兼容修改、额外链接、问题引用和其他元信息
  • 除了feat和fix以外的类型可以在提交信息中使用

徽章

使用了常规提交规范可以添加徽章在README

[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)

实现示例

只有页眉和页尾

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

只有页眉

docs: correct spelling of CHANGELOG

使用了作用域

feat(lang): added polish language

修复了bug

fix: minor typos in code

see the issue for details on the typos fixed

fixes issue #12

FAQ

问：在最初开发阶段如何处理提交信息？

建议像已发布产品一样处理。即使是你的软件开发伙伴在使用软件过程中，也想知道那些被修复了，那些是不兼容修改。

问：提交头的类型名是大写还是小写？

无所谓，不过最好保持一致（一直大写或一直小写）

问：如果提交内容适用于多个类型怎么办？

尽可能返回并进行多次提交。常规提交准则的优势在于它有能力驱动我们进行更加组织化的提交和PR

问：这是否是不鼓励快速开发和快速迭代？

它不鼓励以无序的方式快速开发。它帮助你在有多个开发者的多个项目中进行长期开发

问：常规提交准则是否会限制提交的类型?

常规提交准则鼓励开发者使用更多有确切含义的类型。除此以外，准则的灵活性允许开发组提出更多适用于自己的类型，并随着时间的推移更改这些类型

问：这个准则和SemVer的联系？

fix类型应该翻译成PATCH版本。feat类型应该翻译成MINOR版本。如果提交信息中包含不兼容修改，不管哪种类型，都应该翻译成MAJOR版本

问：如何将扩展版本转换为常规提交规范?

我们建议使用SemVer发布您自己对本规范的扩展（并鼓励您进行这些扩展！）

问：如果我不小心使用了错误的提交类型，该怎么办？

  1. 使用了规范中的类型但是没有使用正确的类型，比如使用fix替代了feat

在合并或者发布这个错误之前，推荐使用git rebase -i进行提交历史编辑。发布之后，依据使用的工具或流程进行清理

  1. 当使用了规范外的类型，比如使用了feet替代了feat

如果提交不符合常规提交规范，它只是意味着基于规范的工具将错过这次提交

问：是否我的所有贡献者都需要使用常规提交规范?

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

commit message 的格式

每次提交，Commit message 都包括三个部分：Header，Body 和 Footer。

<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>

其中，Header 是必需的，Body 和 Footer 可以省略。

不管是哪一个部分，任何一行都不得超过72个字符（或100个字符）。这是为了避免自动换行影响美观。

1.1 Header

Header部分只有一行，包括三个字段：type（必需）、scope（可选）和subject（必需）。

（1）type

type用于说明 commit 的类别，只允许使用下面7个标识。

feat：新功能（feature）
fix：修补bug
docs：文档（documentation）
style： 格式（不影响代码运行的变动）
refactor：重构（即不是新增功能，也不是修改bug的代码变动）
test：增加测试
chore：构建过程或辅助工具的变动

如果type为feat和fix，则该 commit 将肯定出现在 Change log 之中。其他情况（docs、chore、style、refactor、test）由你决定，要不要放入 Change log，建议是不要。

（2）scope

scope用于说明 commit 影响的范围，比如数据层、控制层、视图层等等，视项目不同而不同。

（3）subject

subject是 commit 目的的简短描述，不超过50个字符。

以动词开头，使用第一人称现在时，比如change，而不是changed或changes
第一个字母小写
结尾不加句号（.）

1.2 Body

Body 部分是对本次 commit 的详细描述，可以分成多行。下面是一个范例。

More detailed explanatory text, if necessary.  Wrap it to 
about 72 characters or so. 

Further paragraphs come after blank lines.

- Bullet points are okay, too
- Use a hanging indent

有两个注意点。

（1）使用第一人称现在时，比如使用change而不是changed或changes。

（2）应该说明代码变动的动机，以及与以前行为的对比。

Footer 部分只用于两种情况。

（1）不兼容变动

如果当前代码与上一个版本不兼容，则 Footer 部分以BREAKING CHANGE开头，后面是对变动的描述、以及变动理由和迁移方法。

BREAKING CHANGE: isolate scope bindings definition has changed.

To migrate the code follow the example below:

Before:

scope: {
myAttr: 'attribute',
}

After:

scope: {
myAttr: '@',
}

The removed `inject` wasn't generaly useful for directives so there should be no code using it.

（2）关闭 Issue

如果当前 commit 针对某个issue，那么可以在 Footer 部分关闭这个 issue 。

Closes #234

也可以一次关闭多个 issue 。

Closes #123, #245, #992

1.4 Revert

还有一种特殊情况，如果当前 commit 用于撤销以前的 commit，则必须以revert:开头，后面跟着被撤销 Commit 的 Header。

revert: feat(pencil): add 'graphiteWidth' option

This reverts commit 667ecc1654a317a13331b17617d973392f415f02.

Body部分的格式是固定的，必须写成This reverts commit <hash>.，其中的hash是被撤销 commit 的 SHA 标识符。

如果当前 commit 与被撤销的 commit，在同一个发布（release）里面，那么它们都不会出现在 Change log 里面。如果两者在不同的发布，那么当前 commit，会出现在 Change log 的Reverts小标题下面。

results matching ""

    No results matching ""