Angular 风格 Git 提交消息

AlexSJC
发布于 2024-08-17 / 26 阅读
0
1

Angular 风格 Git 提交消息

https://github.com/angular/angular/blob/main/CONTRIBUTING.md#-commit-message-format

规范

此规范受到 https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit# 的启发并取代了该格式。

我们对 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:用于浏览器扩展的变更。

  • 无/空字符串:对用于 testrefactor 跨所有包完成的更改(如 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>

  • 清楚描述撤销提交消息的原因。


评论