Commit message 编写规范

版次：2023年1月30日 第1.1版
类型：程序文件
作者：软件部
上海维宏电子科技股份有限公司　版权所有

1 目的

编写本规范的目的是为了统一公司代码提交信息风格，提高代码提交信息的可读性、从而提高软件的开发效率。

格式化的 Commit message 有以下好处：

提供更多的历史信息，方便快速浏览。 对于遵循编写规范的 Commit message，只需要看首行，就知道某次 Commit 的目的。

可以过滤某些 Commit （比如文档改动），便于快速查找信息。 比如，可以通过对提交信息过滤显示本次发布新增加的功能。

可以直接从 Commit 生成 Change log。 Change log 是发布新版本时，用来说明与上一个版本差异的文档。

2 适用范围

本规范适用于公司所有产品的软件代码。自本规范实施之日起，以后代码提交信息风格均应执行本规范。

3 Commit message 的格式

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

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

其中，Header 是必需的，Body 和 Footer 可以省略。为了避免自动换行影响美观，要求每一行的字符数不超过72个。

3.1 Header

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

（1）type

type 用于说明 Commit 的类别，只允许使用下面8个标识：

- feature: 新功能 （feature）
- fix: 修补 bug
- doc: 文档（对文档进行了修改）
- style: 格式（不影响代码运行的变动）
- refactor: 重构（即不是新增功能，也不是修改 bug 的代码变动）
- test: 增加测试
- build: 对构建系统或者外部依赖项，CI生成脚本配置进行了修改
- chore: 不符合上述任何类型的相关更改

（2）scope

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

（3）subject

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

以动词开头，使用第一人称现在时，比如 change，而不是 changed 或 changes

第一个字母小写

结尾不加句号（.）

3.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: 修改过期的 scope bindings 定义.

    请参照以下示例要迁移代码：

    Before:

    scope: {
      myAttr: 'attribute',
    }

    After:

    scope: {
      myAttr: '@',
    }

    移除的属性值已经不在有效，因此不应有代码使用它。

（2）关闭 BUG

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

Closes #234

也可以一次关闭多个 bug。

Closes #123, #245, #992

3.4 Revert

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

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

reverts Commit 11212

Body 部分的格式是固定的，必须写成 reverts Commit <变更集号>.。

3.5 案例

feature 案例： 在案例 body 的序列中有用到 -或*，目前不做限制。

feature(CsvExproter): print '0' instead of '-' in the CSV report

- CsvExporter now prints '0' instead of '-' in the report

- Add PrintZeroValuesInContent option in SummaryStyle to control it (by default it is false)

- Add tests to cover changed behavior

Closes #1168

feature: resolve xref recursively (#4314)

* resolve xref recursively

* fix test. ParentNode doesn't work as expected...

chore 案例：

chore: cleanup docs/architecture (#15489)

Autocleanup of MD022 and MD009

chore: clenaup docs/fsharp (#15585)

Ran `markdownlint --fix "docs/fsharp/**/*.md"` to fix MD009 and MD022

Breaking changes 案例： 这个案例没有描述迁移方案，目前待定。

Breaking changes： improvements (#16613)

* move winforms breaking changes to compatibility section

* update core toc; add link to unsupported apis

* add more bookmarks; change title on some include files

* fix typo; add horizontal line; toc title change; add contextual toc link to unavailable techs

revert 案例：

revert: "Improve call counting mechanism (#1457)" (#30105)

* Revert "Revert "Disable test based on #129 (#130)" (#2310)"

This reverts commit 427cd91.

* Revert "Fail FuncEval if slot backpatching lock is held by any thread (#2380)"

This reverts commit fc06054.

* Revert "Improve call counting mechanism (#1457)"

This reverts commit 3a457cb.

test 案例：

test: add missing test cases for ensure and is-ignored (#987) 

* test(esnure): add tests for untested code paths

* test(is-ignored): add test case for untested code path

build 案例：

build: add build script

* Build file to xxx

doc 案例：

doc(angular.copy): fix `getter`/`setter` formatting 

Fix the formatting of `getter`/`setter` in the known limitations section
of the `angular.copy()` docs.

refactor 案例：

refactor: use builtin Object.values instead of lodash/values (#968) 

* refactor: use builtin Object.values instead of lodash

编制：审核：批准：