Git 最佳实践规范

Git 分支的命名约定

当我们使用代码版本控制时，我们应该遵循的主要良好实践之一是为分支、提交、拉取请求等使用清晰且描述性的名称。确保所有团队成员的简洁工作流程至关重要。除了提高生产力之外，记录项目的开发过程还可以简化团队合作。通过遵循这些做法，您很快就会看到好处。

基于此，社区创建了一个您可以在项目中遵循的分支命名约定。以下项目的使用是可选的，但它们可以帮助提高您的开发技能。

1. 小写：分支名称不要使用大写字母，坚持小写；

2. 连字符分隔：如果您的分支名称由多个单词组成，请用连字符分隔它们。遵循烤肉串惯例。避免 PascalCase、camelCase 或 Snake_case；

3. (az, 0-9)：分支名称中仅使用字母数字字符和连字符。避免使用任何非字母数字字符；

4. 请不要使用连续的连字符（–）。这种做法可能会令人困惑。例如，如果您有分支类型（例如功能、错误修复、修补程序等），请改用斜杠 (/)；

5. 避免以连字符结尾分支名称。这是没有意义的，因为连字符分隔单词，并且末尾没有单词可以分隔；

6. 这个做法最重要：使用描述性的、简洁的、清晰的名称来解释分支上做了什么；

分支名称错误

• fixSidebar
• feature-new-sidebar-
• FeatureNewSidebar
• feat_add_sidebar

正确的分支名称

• feature/new-sidebar
• add-new-sidebar
• hotfix/interval-query-param-on-get-historical-data

分支名称约定前缀

有时分支的目的并不明确。它可以是新功能、错误修复、文档更新或其他任何内容。为了解决这个问题，通常的做法是在分支名称上使用前缀来快速解释分支的用途。

• feature：它传达了将要开发的新功能。例如，feature/add-filters;

• release：用于准备新版本。该前缀release/通常用于在合并来自分支主服务器的新更新以创建版本之前执行诸如上次触及和修订之类的任务。例如，release/v3.3.1-beta;

• bugfix：它表示您正在解决代码中的错误，并且它通常与问题相关。例如，bugfix/sign-in-flow;

• hotfix：与bugfix类似，但它与修复生产环境中存在的严重错误有关。例如，hotfix/cors-error;

• docs：编写一些文档。例如，docs/quick-start;

如果您正在使用任务管理工作流程，例如 Jira、Trello、ClickUp 或任何可以创建用户故事的类似工具，则每张卡片都有一个关联的编号。因此，通常在分行名称的前缀上使用这些卡号。例如：

• feature/T-531-add-sidebar

• docs/T-789-update-readme

• hotfix/T-142-security-path

提交消息

让我们来谈谈提交消息。不幸的是，很容易找到带有“添加了很多东西”或“皮卡丘，我选择你”之类的提交消息的项目…是的，我曾经发现一个项目，其中提交消息与神奇宝贝战斗有关。

提交消息在开发过程中非常重要。创造一段美好的历史将在你的旅程中给你很多帮助。与分支一样，提交也有社区创建的约定，您可以在下面了解：

提交消息包含三个重要部分：主题、描述和页脚。提交的主题是必需的，它定义了提交的目的。描述（正文）用于为提交的目的提供额外的上下文和解释。最后是页脚，通常用于元数据，例如分配提交。虽然同时使用描述和页脚被认为是一种很好的做法，但这不是必需的。

在消息行中使用祈使句。例如：

Add README.md✅;
Added README.md❌;
Adding README.md❌;

消息行的第一个字母大写。例如：

Add user authentication✅;
add user authentication❌;

不要以句号结束消息行。例如：

Update unit tests✅;
Update unit tests.❌;

消息行限制在50个字符以内，即清晰、简洁；

将正文包裹在72 个字符处，并将消息与空行分隔开；

如果您的提交正文有多个段落，请使用空行将它们分开；

如有必要，使用项目符号而不是仅使用段落；

常规提交

“常规提交规范是基于提交消息的轻量级约定。它提供了一组简单的规则来创建显式提交历史记录。”

以下引用来自Conventional Commit 的官方网站。该规范是社区中提交消息最​​常用的约定。

结构

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
1
2
3
4
5

提交类型

我们要研究的第一个结构是提交类型。它提供了有关此提交中所做操作的清晰上下文。您可以在下面看到提交类型列表以及何时使用它们：

• feat：引入新功能；
• fix：修复软件错误；
• refactor：用于代码更改，保留其整体功能；
• chore：不影响生产代码的更新，涉及工具、配置或库调整；
• docs：对文档文件的添加或修改；
• perf：代码更改提高性能；
• style：与代码呈现相关的调整，例如格式和空白；
• test：测试的包含或修正；
• build：影响构建系统或外部依赖项的修改；
• ci： CI 配置文件和脚本的更改；
• env：描述 CI 流程中配置文件的调整或添加，例如容器配置参数。

范围

范围是一种结构，可以在提交类型之后添加以提供额外的上下文信息：

• fix(ui): resolve issue with button alignment

• feat(auth): implement user authentication

详情

提交消息的正文提供了有关提交引入的更改的详细说明。它通常添加在消息行后面的空白行之后。

例子：

Add 添加新功能来处理用户身份验证。

此提交引入了一个新模块来管理用户身份验证。它包括
用户登录、注册和密码恢复功能。
1
2
3
4

页脚

提交消息的页脚用于提供与提交相关的附加信息。这可以包括诸如谁审查或批准了变更之类的详细信息。

例子：

Signed-off-by: John <john.doe@example.com>
Reviewed-by: Anthony <anthony@example.com>
1
2

重大改变

指示提交包含可能导致兼容性问题或需要修改相关代码的重大更改。您可以BREAKING CHANGE在页脚中添加或包含!在类型/范围之后。

使用常规提交的提交示例

chore: add commitlint and husky
chore(eslint): enforce the use of double quotes in JSX
refactor: type refactoring
feat: add axios and data handling
feat(page/home): create next routing
chore!: drop support for Node 18
1
2
3
4
5
6

包含消息、正文和页脚：

feat: add function to convert colors in hexadecimal to rgba

Lorem Ipsum is simply dummy text of the printing and typesetting industry.

Lorem Ipsum has been the industry's standard dummy text ever since the 1500s.

Reviewed-by: 2
Refs: #345
1
2
3
4
5
6
7
8

引用

• https://www.conventionalcommits.org
• https://medium.com/@abhay.pixolo/naming-conventions-for-git-branches-a-cheatsheet-8549feca2534
• https://se-education.org/guides/conventions/git.html
• https://cbea.ms/git-commit/ https://blog.geekhunter.com.br/o-que-e-commit-e-como-usar-commits-semanticos/