规范
此规范受到
我们对 Git 提交消息的格式有非常精确的规则。这种格式使提交历史记录更易于阅读。
每个提交消息由标题、正文和页脚组成。
<header>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
header
是必要的,必须符合提交消息头格式。
除“文档”类型的提交外,所有提交都必须包含 body
。如果包含正文,则正文长度必须至少为 20 个字符,并且必须符合提交消息正文格式。
footer
是可选的。提交消息页脚格式描述了页脚的用途以及它必须具有的结构。
提交消息头
<type>(<scope>): <short summary>
│ │ │
│ │ └─⫸ Summary in present tense. Not capitalized. No period at the end.
│ │
│ └─⫸ 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|
│ devtools
│
└─⫸ Commit Type: build|ci|docs|feat|fix|perf|refactor|test
<type>
和 <summary>
字段是必填项,(<scope>)
字段是选填项。
类型 <type>
必须是下列之一:
build:影响构建系统或外部依赖项的更改(示例范围:gulp、broccoli、npm)
ci:对我们的 CI 配置文件和脚本的更改(例如:CircleCi、SauceLabs)
docs:仅更改文档
feat : 新功能
fix:错误修复
perf:提高性能的代码更改
refactor:既不修复错误也不添加功能的代码更改
test:添加缺失的测试或更正现有的测试
范围 <scope>
范围应该是受影响的 npm 包的名称(由阅读提交消息生成的更改日志的人感知)。
以下是支持的范围列表:
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
:用于更改我们所有包中的 npm 包布局,例如公共路径更改、对所有包进行的 package.json 更改、d.ts 文件/格式更改、捆绑包更改等。changelog
:用于更新 CHANGELOG.md 中的发布说明dev-infra
:用于目录 /scripts 和 /tools 中的 dev-infra 相关更改docs-infra
:用于 repo 的 /adev 目录中 docs-app(angular.dev)相关的更改migrations
:用于更改ng update
迁移。devtools
:用于浏览器扩展的变更。无/空字符串:对用于
test
和refactor
跨所有包完成的更改(如test: add missing unit tests
)以及与特定包无关的文档更改(如docs: fix typo in tutorial
)有用。
摘要 <summary>
使用摘要字段提供变更的简洁描述:
使用命令式、现在时:“change”,而不是“changed”或“changes”
不要将首字母大写
末尾没有点(.)
提交消息正文
正如在摘要中一样,使用命令式、现在时:“fix”,而不是“fixed”或“fixes”。
在提交消息正文中解释更改的动机。此提交消息应解释您进行更改的原因。您可以将以前的行为与新行为进行比较,以说明更改的影响。
提交消息页脚
页脚可以包含有关重大更改和弃用的信息,也是引用 GitHub 问题、Jira 票证以及此提交关闭或与之相关的其他 PR 的地方。例如:
BREAKING CHANGE: <breaking change summary>
<BLANK LINE>
<breaking change description + migration instructions>
<BLANK LINE>
<BLANK LINE>
Fixes #<issue number>
或者
DEPRECATED: <what is deprecated>
<BLANK LINE>
<deprecation description + recommended update path>
<BLANK LINE>
<BLANK LINE>
Closes #<pr number>
重大变化部分应以短语 BREAKING CHANGE:
开头,后跟重大变化的摘要、空白行以及重大变化的详细描述(其中还包括迁移说明)。
类似地,弃用部分应该以 DEPRECATED:
开头,后跟弃用内容的简短描述、空白行以及弃用的详细描述,其中还需提到建议的更新路径。
恢复提交
如果提交撤销了以前的提交,它应该以 revert:
开头,后跟撤销的提交的标题。
提交消息体的内容应该包含:
有关正在还原的提交的 SHA 的信息,格式如下:
This reverts commit <SHA>
,清楚描述撤销提交消息的原因。