Commit Message Editor使用指南

Commit Message Editor是VSCode中生成格式化提交信息的工具

开篇

与其说这是一篇Commit Message Editor插件的使用指南，不如说，是在想教会我自己如何编写Commit Message。

Commit Message Editor插件只是实现Commit Message标准化的方法，而Commit Message的内容，才是核心。换句话说，使用的工具不局限于Commit Message Editor，只是它，恰好顺手。

关于如何编写Commit Message，互联网上不乏经典的案例与详细的教程。但于我而言，那终究还是别人的知识，只有自己经过学习、思考、归纳和总结后，为己所用，才算是成为自己的东西。

所以本文诞生了。

Commit Message

提交消息（Commit Message）是git工作流中一个重要的组成部分。

Git工作流

假如你接触过代码编写，哪怕只是一个轻量的shell脚本，应该会对“版本管理”有所耳闻。Git就是一个很好用的版本管理工具，它是一个分布式的版本控制系统，能跟踪代码文件中的变化，目的在于协调协作开发源代码的程序员之间的工作。关于它，你可以在Getting Started - What is Git?中获取更多的知识。

Commit Message简介

将你的代码提交保存，是git工作流中必须的一个流程。在进行代码提交时，Commit Message（提交消息）是一个必须的内容。虽然在Commit Message为空的情况下，git不会拒绝你提交代码，但这并不是一个正确的做法。

一个好的 Commit Message 应该清晰明了地描述本次提交的内容，以方便其他开发人员能够快速了解代码变更的目的，以及变更的影响范围。如果 Commit Message 的内容为空，其他开发人员就无法快速了解这次提交的目的，这会给团队协作带来不便。因此，在提交代码时，应该尽量编写清晰明了的 Commit Message，这对于团队协作和代码管理都非常重要。

Commit Message作用

关于它的作用，上文有些许涉及，这里还是要详细说明一下Commit Message的作用，以引起足够的重视。我们都希望事物能够按着预定的规则良好地发展。

Commit Message 的作用主要有以下几个方面：

记录代码变更历史。Commit Message 记录了每次提交代码的目的和变更内容，能够帮助开发人员回顾代码变更历史，了解代码的演进过程。
方便团队协作。一个好的 Commit Message 能够让其他开发人员快速了解本次提交的目的和变更的影响范围，从而更好地协作开发。
便于代码审查。Commit Message 描述了本次提交的目的和变更内容，能够帮助代码审查人员更好地了解代码变更的目的和影响范围，从而更好地进行代码审查。

Commit Message格式

令人出乎意料的是，Commit Message并没有固定的格式，开发者可以按照喜好制定一些格式。但也有一些被大众所接受的格式可供选择，如[Conventional、Gitmoji等，其中Conventional格式源于AngularJS，并在此基础上进行完善，现在已成为一个开放的社区标准。本文记录的格式是Conventional，这是被最多人使用的一种格式。

Conventional Commits

关于Conventional Commits你想知道的一切信息，你都可以在Conventional官方网站上找到，那里对Conventional Commits规范进行了详尽的解释与常见问题的答疑。

从结构上来看，Conventional Commits的内容分为五个部分：类型、范围、描述、正文和脚注。

<类型>[可选 范围]: <描述>

[可选 正文]

[可选 脚注]

类型（type）

类型是一个必选内容，可以用于快速判断对项目进行了哪方面的修改，它必须是以下项目之一：

build：用于影响构建系统或外部依赖项的更改，例如gulp、broccoli、npm等
ci：在更改项目的 CI 配置文件和脚本时使用
docs：用于对项目的说明文档进行的更改
feat：增加一项新功能时使用
fix：修复错误时使用
perf：应用于提高性能的代码的更改
refactor：重构，用于既不修复错误也不添加功能的代码更改
style：对项目进行不影响代码含义的更改时使用，如空格、格式修改、缺少分号等
test：添加缺少的测试或更正现有测试
chore：对构建、工具、文档等方面进行的修改时使用，这些秀修改通常不会对代码功能或接口产生影响，只是一些日常的维护工作或者是一些辅助性的修改

对于上述类型的应用，还应遵守以下几条规则：

每个提交都必须使用类型字段前缀，它由一个名词构成，诸如 feat 或 fix ，其后接可选的范围字段，可选的 !，以及必要的冒号（英文半角）和空格
当一个提交为应用或类库实现了新功能时，必须使用 feat 类型
当一个提交为应用修复了 bug 时，必须使用 fix 类型

范围（scope）

范围是一个可选的内容，它用于表示本次提交的修改的作用范围，一般填写修改涉及到的模块或组件名称。

scope内容由一个单词或短语构成，并用圆括号括起来，以下是一个示例：

fix(api):

它表示本次提交的修改作用在用户认证上，即auth模块。

使用 scope 可以更清晰地说明本次修改的范围，方便其他开发者理解和追踪代码变更，也有助于更好地组织和管理代码。此外，一些工具和平台（如 GitHub）也可以根据 scope 进行过滤和分类，方便查找和管理代码。

描述（description）

这是一个必填项，对提交的修改进行总结性的描述，通常是一句话，需要遵守以下规则：

第一个字母不要大写
不以句号为结尾
使用现在时：“change”不是“changed”也不是“changes”
描述必须直接跟随在<类型>[范围]前缀的冒号和空格之后

fix: prevent racing of requests

正文（body）

简短的描述后面，可以编写较长的提交正文，用于详细说明提交的信息：解释进行更改的原因，也可以将以前的行为与新行为进行比较，以说明更改带来的影响。

正文必须起始于描述字段结束的一个空行后。换句话说，正文与描述之间，必须空一行
提交的正文内容自由编写，并可以使用空行分隔不同段落
使用文本格式进行编写，不要使用任何标记性语言，如markdown
使用祈使句、现在时：“fix”不是“fixed”也不是“fixes”

fix(api): 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.

脚注（footer(s)）

footer是提交信息的最后一行，用于提供额外的元数据或引用问题跟踪器等信息。footer 可以包含一个或多个关键字和值，它们用冒号分隔。

正文结束的第一个空行后，可以编写一行或多行脚注
每行脚注都必须包含一个关键字（token），后面紧跟 :<space>（冒号和空格）或 <space>#（空格和#号）作为分隔符，后面再紧跟令牌的值。例如：Issue: #666或Issue ##666
脚注的关键字必须使用 - 作为连字符，比如 Acked-by (这样有助于区分脚注和多行正文)。有一种例外情况就是 BREAKING CHANGE，它可以被认为是一个关键字
脚注的值可以包含空格和换行，值的解析过程必须直到下一个脚注的令牌/分隔符出现为止

fix(api): 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: kanochan
Issue: #666

关于破坏性的变更（BREAKING CHANGE），有几个额外的约定：

破坏性变更必须在提交信息中标记出来，要么在 <类型>(范围) 前缀中标记，要么作为脚注的一项
包含在脚注中时，破坏性变更必须包含大写的文本 BREAKING CHANGE，后面紧跟着:<space>，然后是描述，例如： BREAKING CHANGE: environment variables now take precedence over config files
包含在 <类型>(范围) 前缀时，破坏性变更必须通过把 ! 直接放在 : 前面标记出来，例如：feat(api)!: send an email to the customer when a product is shipped。如果使用了 !，那么脚注中可以不写 BREAKING CHANGE:，同时提交信息的描述中应该用来描述破坏性变更
工具的实现必须不区分大小写地解析构成约定式提交的信息单元，只有 BREAKING CHANGE 必须是大写的
BREAKING-CHANGE 作为脚注的关键字时必须是 BREAKING CHANGE 的同义词（如果你在提交信息的 footer 中使用 BREAKING-CHANGE 作为关键字，那么它必须与 BREAKING CHANGE 是同义词，而不能是其他类似的词语或缩写。这是因为许多工具和流程依赖于这个特定的关键字来识别破坏性变更，如果使用了其他类似的词语或缩写，这些工具可能无法正确地处理这个提交。因此，如果你想在提交信息中指定破坏性变更，应该使用 BREAKING CHANGE 这个特定的关键字，而不是其他类似的词语或缩写。）

包含了 ! 和 BREAKING CHANGE 脚注的提交说明

chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

包含了范围和破坏性变更 ! 的提交說明

feat(api)!: send an email to the customer when a product is shipped

包含了描述并且脚注中有破坏性变更的提交说明

feat: allow provided config object to extend other configs

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

Commit Message Editor

说回正题，Commit Message Editor是VSCode上的一个提交消息编辑器插件，它提供了一个可视化的界面来编写规范的Commit Message。它支持Conventional Commits规范，并提供了一些可定制的选项，以帮助你更好地管理提交历史。除此之外，它还支持自定义模板和快捷键，能够更快地编写Commit Message。