约定式分支 1.0.0

概述

约定式分支是指 Git 分支的结构化和标准化命名约定，旨在使分支更具可读性和可操作性。我们建议了一些您可能想要使用的分支前缀，但您也可以指定自己的命名约定。一致的命名约定使按类型识别分支变得更加容易。

要点

以目的为导向的分支名称：每个分支名称都清楚地表明了其目的，使所有开发人员都能轻松了解该分支的用途。
与 CI/CD 集成：通过使用一致的分支名称，它可以帮助自动化系统（如持续集成/持续部署管道）根据分支类型触发特定操作（例如，从发布分支自动部署）。
团队协作：它通过明确分支目的来鼓励团队内部的协作，减少误解并使团队成员更容易在任务之间切换而不会产生混淆。

规范

分支命名前缀

分支规范支持以下前缀，其结构应如下：

<type>/<description>

main：主要开发分支（例如 main、master 或 develop）
feature/ (或 feat/)：用于新功能（例如 feature/add-login-page, feat/add-login-page）
bugfix/ (或 fix/)：用于错误修复（例如 bugfix/fix-header-bug, fix/header-bug）
hotfix/：用于紧急修复（例如 hotfix/security-patch）
release/：用于准备发布的分支（例如 release/v1.2.0）
chore/：用于非代码任务，如依赖项、文档更新（例如 chore/update-dependencies）

基本规则

使用小写字母、数字、连字符和点：分支名称应全部使用小写字母 (a-z)、数字 (0-9) 及连字符 (-) 进行分隔。避免使用特殊字符、下划线或空格。对于 release 分支，可以在描述中使用点 (.) 来表示版本号（例如 release/v1.2.0）。
禁止连续、开头或结尾的连字符或点：确保连字符和点不能连续出现（例如 feature/new--login, release/v1.-2.0），也不能出现在描述的开头或结尾（例如 feature/-new-login, release/v1.2.0.）。
保持清晰简洁：分支名称应简明扼要，清楚表达工作的内容和目的。
包含工单编号：如果适用，应包含项目管理工具中的工单编号，以便于追踪。例如，对于工单 issue-123，分支名称可以是 feature/issue-123-new-login。

形式文法

以下 ABNF（扩充巴科斯-诺尔范式）文法正式定义了有效的分支名称：

branch-name     = trunk-branch / prefixed-branch
trunk-branch    = "main" / "master" / "develop"
prefixed-branch = type "/" description
type            = "feature" / "feat" / "bugfix" / "fix"
                / "hotfix" / "release" / "chore"
description     = desc-segment *("-" desc-segment)
desc-segment    = 1*(ALPHA / DIGIT) *("." 1*(ALPHA / DIGIT))
ALPHA           = %x61-7A   ; 小写字母 a-z
DIGIT           = %x30-39   ; 数字 0-9

注意：禁止连续的连字符或点，以及出现在描述开头或结尾的连字符或点。

示例

分支名称	有效	说明
`main`	✅	主干分支
`master`	✅	主干分支
`develop`	✅	主干分支
`feature/add-login-page`	✅	新功能
`feat/add-login-page`	✅	feature 的简写形式
`bugfix/fix-header-bug`	✅	错误修复
`fix/header-bug`	✅	bugfix 的简写形式
`hotfix/security-patch`	✅	紧急修复
`release/v1.2.0`	✅	含版本号的发布分支
`chore/update-dependencies`	✅	非代码任务
`feature/issue-123-new-login`	✅	含工单编号的功能分支
`Feature/Add-Login`	❌	不允许大写字母
`feature/new--login`	❌	不允许连续连字符
`feature/-new-login`	❌	描述不能以连字符开头
`feature/new-login-`	❌	描述不能以连字符结尾
`release/v1.-2.0`	❌	连字符不能紧邻点号
`fix/header bug`	❌	不允许空格
`fix/header_bug`	❌	不允许下划线
`unknown/some-task`	❌	未知的前缀类型

结论

清晰的沟通：仅凭分支名称就能清楚地了解代码更改的目的。
自动化友好：轻松挂接自动化流程（例如，针对 feature, release 等的不同工作流程）。
可扩展性：适用于许多开发人员同时处理不同任务的大型团队。

总之，约定式分支旨在改善 Git 工作流程中的项目组织、沟通和自动化。

常见问题

为什么分支类型不像 Conventional Commits（例如 `build`、`ci`、`docs`、`style`、`refactor`）那么详细？

分支与提交不同 —— 分支是临时的，大部分只出现在合并前。为分支引入过多类型是没有必要的，也会让管理和记忆变得更困难。

如果团队成员不符合此规范，可以使用哪些工具来自动识别？

你可以使用 commit-check 来检查分支规范，或者如果你的代码托管在 GitHub 上，则使用 commit-check-action。

我可以定义规范列表之外的自定义分支类型吗？

可以。本规范定义了一套推荐的类型，但团队可以根据工作流程定义额外的自定义类型。重要的是，需要将自定义类型清楚地记录下来，以便所有团队成员和自动化工具都能了解。

约定式分支与约定式提交（Conventional Commits）有什么关系？

约定式分支的灵感来源于 Conventional Commits，遵循相似的理念：为 Git 元数据引入人机可读的结构。约定式提交规范化了提交信息，约定式分支规范化了分支名称。两者相辅相成，天然互补。

如何处理 `develop` 或 `staging` 等长期存在的分支？

长期存在的集成或环境分支（如 develop，以及某些项目约定使用的 staging、production 等）通常被视为主干分支，不需要前缀，并应在整个项目中保持一致的命名。需要注意的是，在上文给出的 ABNF 语法中，trunk-branch 形式规则只包含 main / master / develop；staging、production 等仅作为各团队可选的长期分支示例，不属于该形式语法的一部分，语法校验工具可按需要在此基础上扩展支持。

约定式分支