Posted Updated Git11 minutes read (About 1619 words)

Git Commit Message 规范

在 GitHub 上大多数知名项目的 Git Commit Message 其实都没有具体的规范，其他更多的仓库的 Git Commit Message 更是五花八门，有的甚至没有写 Commit Message 或乱写。

规范的 Commit Message 在 review 代码的时候会更清晰，甚至通过 conventional-changelog 可以根据规范的 Commit 自动生成 changlogs 和 release notes。

这是改编自Angular 的提交约定。

提交消息格式

本规范的灵感来自并取代了AngularJS 提交消息格式。

我们对如何格式化 Git 提交消息有非常精确的规则。这种格式导致更容易阅读提交历史。

每个提交消息都由一个header、一个body和一个footer组成。

1
2
3
4
5
<header>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
  • header是强制性的。
  • 除了“docs”类型的body提交之外，所有提交都是强制性的。当正文出现时，它必须至少有 20 个字符长并且必须符合 提交消息正文 格式。
  • footer`是可选的。提交消息页脚 格式描述了页脚的用途和它必须具有的结构。

Commit Message Header

1
2
3
4
5
6
7
8
9
10
11
<type>(<scope>): <short summary>
  │       │             │
  │       │             └─⫸ 用现在时概括。没有大写。最后没有句号。
  │       │
  │       └─⫸ Commit Scope: animations|bazel|benchpress|common|compiler|compiler-cli|core|
  │                          elements|forms|http|language-service|localize|platform-browser|
  │                          platform-browser-dynamic|platform-server|router|service-worker|
  │                          upgrade|zone.js|packaging|changelog|docs-infra|migrations|ngcc|ve|
  │                          devtools
  │
  └─⫸ Commit Type: build|workflow|ci|docs|feat|fix|polish|perf|refactor|test|chore

<type>和<summary>字段是必需的，字段(<scope>)是可选的。

type

Type 必须是以下之一：

  • build：影响构建系统或外部依赖项的更改（示例范围：gulp、broccoli、npm）
  • ci：更改我们的 CI 配置文件和脚本（例如：CircleCi、SauceLabs）
  • docs：仅文档更改
  • feat：一个新功能
  • fix：错误修复
  • polish: 改进，完善
  • perf：提高性能的代码更改
  • refactor：既不修复错误也不添加功能的代码更改
  • test：添加缺失的测试或纠正现有的测试
  • chore: 杂活（例如：chore: fix typo (#60)）

如果前缀是feat,fix或perf，它将出现在更新日志中。但是，如果有任何BREAKING CHANGE，则提交将始终出现在更改日志中。

其他前缀由您自行决定。建议的前缀是docs, chore, style, refactor, 和test用于非变更日志相关的任务。

scope

范围可以是指定提交更改位置的任何内容。例如 Vue.js 中的core, compiler, ssr,v-model等transition…

summary

summary 即摘要。

使用摘要字段提供更改的简洁描述：

  • 使用祈使语气，现在时：“change”不是“changed”也不是“changes”
  • 第一个字母不要大写
  • 末尾没有点 (.)

Commit Message Body

就像在摘要中一样，使用祈使语气，现在时：“fix”不是“fixed”也不是“fixes”。

解释提交消息正文中更改的动机。此提交消息应解释您进行更改的原因。您可以将先前行为与新行为进行比较，以说明更改的影响。

页脚可以包含有关重大更改和弃用的信息，也是引用 GitHub 问题、Jira 票证和此提交关闭或相关的其他 PR 的地方。例如：

1
2
3
4
5
6
BREAKING CHANGE: <breaking change summary>
<BLANK LINE>
<breaking change description + migration instructions>
<BLANK LINE>
<BLANK LINE>
Fixes #<issue number>

或者

1
2
3
4
5
6
DEPRECATED: <what is deprecated>
<BLANK LINE>
<deprecation description + recommended update path>
<BLANK LINE>
<BLANK LINE>
Closes #<pr number>

重大变更部分应以短语“BREAKING CHANGE:”开头，后跟重大变更摘要、空白行和包括迁移说明的重大变更的详细说明。

类似地，弃用部分应以“DEPRECATED：”开头，然后是弃用内容的简短描述、空行和弃用的详细描述，其中还提到了推荐的更新路径。

Revert

如果提交还原了先前的提交，它应该以 开头revert: ，后跟还原提交的标头。在正文中，它应该说：This reverts commit <hash>.，其中哈希是被还原的提交的 SHA。

例子

Angular

angular 代码提交消息是非常规范的，下面列举 angular/angular: The modern web developer’s platform 代码提交消息示例。

1
2
build: update dependency @types/chrome to ^0.0.184 (#1)
PR Close #1
1
2
docs: update readme (#32084)
PR Close #32084
1
2
3
4
docs: add template overview doc (#45897)
Organize bottom list into cards.

PR Close #45897
1
2
3
docs: update tagline (#41922)
Seems like the tagline has changed on the [Angular Twitter account](https://twitter.com/angular) and angular.io. This change makes this doc in line with those two resources.
PR Close #41922
1
2
3
4
5
6
7
fix(docs-infra): correctly style the CLI version in code snippet (#46020)
Some CLI versions (such as `@next`) are not parsed (and thus not
formatted) correctly in code snippets. Fix this by explicitly adding an
appropriate CSS class to the `<aio-angular-dist-tag>` elements to let
PrettyPrint know how to style this token.

PR Close #46020
1
2
3
4
5
6
feat(devtools): support icons in offline mode (#45430) (#45743)
Add support to material design icons in offline mode for Angular Devtools. Self hosting the web font so icons are loaded regardless of network connection.

Bring the font file as well as its corresponding css file from third_party repo through bazel into shell-browser directory while building.

PR Close #45743
1
2
3
4
test(core): reset Testability getter after each test (#45947)
This commit updates the Testability-related tests to reset the testability getter class after each test to avoid leaking the state between tests. This should improve the stability of the testability tests that are currently flaky on CI.

PR Close #45947

Vue

1
release: v3.2.33

出现在“Features”标题下，子标题compiler：

1
feat(compiler): add 'comments' option
1
feat(compiler): add 'comments' option

出现在“Bug Fixes”标题、子标题下v-model，带有指向问题 #28 的链接：

1
2
3
fix(v-model): handle events on blur

close #28

出现在“性能改进”标题下，并在“重大更改”下显示重大更改说明：

1
2
3
perf(core): improve vdom diffing by removing 'foo' option

BREAKING CHANGE: The 'foo' option has been removed.

如果它们在同一版本下，则以下提交和提交667ecc1不会出现在更改日志中。如果没有，恢复提交将出现在“Reverts”标题下。

1
2
3
revert: feat(compiler): add 'comments' option

This reverts commit 667ecc1654a317a13331b17617d973392f415f02.

页脚应包含有关Breaking Changes的任何信息，也是引用此提交Closes的 GitHub 问题的地方。

重大更改BREAKING CHANGE:应以带有空格或两个换行符的单词开头。然后将提交消息的其余部分用于此目的。

Git Commit Message 规范

https://ganzhixiong.com/p/22b26c8/

Author

干志雄

Posted on

2022-05-19

Updated on

2022-05-19

Licensed under

 
,   
,   

Like this article? Support the author with

Comments

Recents

×