版本： 2.0
适用范围： 通用软件工程团队（与具体项目/产品线无关）
参考标准： Conventional Commits、Semantic Versioning、Git Flow、GitHub Flow

---

1. 总则

1.1 命名基本原则

规则	说明
全小写	分支名、标签名一律使用小写字母与数字
连字符分隔	多词之间用 -（kebab-case），不使用 _ 或驼峰
斜杠分层	短期分支使用 <类型>/<描述> 形式，便于分组与权限管理
语义清晰	名称应体现变更类型 + 变更意图，避免 fix、temp、test 等无意义命名
短而准	描述部分建议 2～5 个英文单词，总长不超过 50 字符
ASCII 优先	优先使用英文；若团队统一使用中文拼音，需全团队一致并写入规范

1.2 推荐与禁止示例

推荐

feature/user-authentication
fix/login-session-expiry
hotfix/payment-timeout
release/1.4.0

禁止

feature/fix              # 语义不明
Feature/UserAuth         # 大小写混用
feature_user_auth        # 使用下划线
dev-zhangsan-20240710    # 含人名/日期的临时分支
wip                      # 无类型前缀

1.3 分支策略选型

团队应在以下模型中择一为主，并在规范中明确默认合入目标：

模型	适用场景	核心长期分支
GitHub Flow	持续交付、Web/SaaS、单主干	main
Git Flow	版本化发布、需发布冻结期	main + develop
Trunk-Based Development	高频集成、强 CI/CD	main（短期分支 ≤ 2 天）

下文以 Git Flow + Conventional Commits 为默认叙述（业界最常见组合），采用 GitHub Flow 的团队可忽略 develop 相关条目。

---

2. 长期分支（Long-lived Branches）

长期分支受保护（Protected Branch），禁止直接 force push，仅通过 Pull Request / Merge Request 合入。

分支名	用途	说明
main	生产基线	与线上发布版本一致；仅接受 release/*、hotfix/* 合入（Git Flow）或所有已评审变更（GitHub Flow）
master	生产基线（历史命名）	与 main 等价；新仓库优先使用 main
develop	集成开发主干	日常开发集成分支；功能/fix 分支的默认合入目标（Git Flow）

约束

• 长期分支禁止 --force 推送
• 合入前须通过 CI 与 Code Review
• 不在长期分支上直接开发（紧急 hotfix 除外）

---

3. 短期分支（Short-lived Branches）

从对应的长期分支拉取，完成工作后通过 PR/MR 合入，合入后删除远程分支。

3.1 功能分支 — feature/

用于新功能、需求迭代、非紧急重构。

feature/<简短描述>
feature/<issue-id>-<简短描述>    # 关联 Issue 时推荐

字段	规则	示例
简短描述	动宾或名词短语，kebab-case	oauth2-login、export-csv
issue-id	可选，与 Tracker 一致	123、PROJ-456

示例

feature/oauth2-login
feature/123-export-user-report
feature/shopping-cart-checkout

工作流（Git Flow）

develop ──► feature/oauth2-login ──► PR ──► develop

3.2 缺陷修复分支 — fix/ 或 bugfix/

用于开发/测试阶段发现的缺陷修复（非生产紧急问题）。

fix/<简短描述>
fix/<issue-id>-<简短描述>

示例

fix/null-pointer-on-logout
fix/456-email-validation-regex

fix/ 与 bugfix/ 语义相同，团队择一统一；Conventional Commits 中对应类型均为 fix。

与 hotfix/ 的区别见 §3.3。

3.3 热修复分支 — hotfix/

用于生产环境紧急修复。从 main（或 master）拉取，修复后合入 main 并回合并入 develop（Git Flow）。

hotfix/<简短描述>
hotfix/<版本号>-<简短描述>    # 多热修并行时可加版本号

示例

hotfix/payment-gateway-timeout
hotfix/1.2.1-session-leak

工作流（Git Flow）

main ──► hotfix/payment-gateway-timeout ──► PR ──► main
                                        └──► PR ──► develop

3.4 发布分支 — release/

用于发布前版本冻结、CHANGELOG 整理、版本号 bump、回归测试。从 develop 拉取，完成后合入 main 并打 Tag，再回合并入 develop。

release/<主版本>.<次版本>.<修订号>

遵循 Semantic Versioning：MAJOR.MINOR.PATCH

示例

release/1.4.0
release/2.0.0-rc.1    # 预发布版本（可选）

3.5 重构分支 — refactor/

不改变外部可观测行为的大规模结构调整。

refactor/<简短描述>

示例

refactor/extract-payment-service
refactor/migrate-to-vitest

3.6 工程化分支 — chore/

构建脚本、依赖升级、CI 配置、工具链变更等非业务代码。

chore/<简短描述>

示例

chore/upgrade-node-20
chore/add-dependabot-config

3.7 文档分支 — docs/

仅文档变更（若与功能同 PR 可不必单独建分支）。

docs/<简短描述>

示例

docs/api-authentication-guide
docs/update-contributing

3.8 实验分支 — experiment/ 或 spike/

概念验证、技术调研；不得直接合入 main，结论沉淀后以 feature/ 或 refactor/ 重新提交。

experiment/<简短描述>

3.9 禁止的分支命名模式

模式	原因
dev-<用户名>、tmp-*	个人临时分支易泄漏、难追溯
纯数字、纯日期	无语义
含空格或特殊字符	跨平台/Git 工具兼容性问题
与长期分支同名前缀混淆	如 main-backup、develop-old

---

4. Tag 命名规范

发布 Tag 与 release/* 分支版本号保持一致，遵循 Semantic Versioning。

v<主版本>.<次版本>.<修订号>
v<主版本>.<次版本>.<修订号>-<预发布标识>.<序号>    # 预发布

示例

v1.4.0
v1.4.1              # patch：向后兼容的 bug 修复
v2.0.0              # major：含破坏性变更
v1.5.0-beta.1       # 预发布
v1.5.0+build.20240710   # 构建元数据（可选）

约束

• Tag 仅打在 main（或发布 commit）上
• 禁止移动已推送的 Tag；若需修正，使用新的 patch 版本号
• Annotated Tag 优于 Lightweight Tag（含作者、日期、说明）

git tag -a v1.4.0 -m "Release 1.4.0: OAuth2 login, CSV export"

---

5. Commit Message 规范

采用 Conventional Commits 规范，便于自动生成 CHANGELOG、语义化版本号（semantic-release）及代码审查。

5.1 基本格式

<类型>[可选 作用域]: <描述>

[可选 正文]

[可选 脚注]

单行示例（最常见）

feat(auth): add OAuth2 authorization code flow
fix(cart): prevent duplicate item on rapid click
docs(readme): update local development setup

5.2 类型（Type）

类型	含义	语义化版本影响
feat	新功能	MINOR ↑
fix	缺陷修复	PATCH ↑
docs	仅文档	—
style	格式（空格、分号等，不影响逻辑）	—
refactor	重构（非 feat/fix）	—
perf	性能优化	PATCH ↑（部分工具）
test	测试增删改	—
build	构建系统或外部依赖	—
ci	CI 配置与脚本	—
chore	其他不修改 src/test 的维护性工作	—
revert	回滚先前提交	视被回滚内容

破坏性变更（Breaking Change）

在类型后加 !，或在脚注写 BREAKING CHANGE:：

feat(api)!: remove deprecated v1 endpoints

BREAKING CHANGE: /api/v1/* routes removed; migrate to /api/v2/*

5.3 作用域（Scope）

可选，表示变更影响的模块/包/层级：

feat(auth): ...
fix(payment/stripe): ...
chore(deps): ...

团队应维护一份推荐 scope 列表（如 auth、api、ui、db），但不强制穷举。

5.4 描述（Subject）约束

规则	说明
祈使语气	英文用 "add" 而非 "added"；中文可用「添加」
首字母	英文描述首字母小写（专有名词除外）
无句号	Subject 末尾不加 .
长度	不超过 72 字符（50 字符以内更佳）
语言	全团队统一中文或英文，不混用

5.5 正文（Body）与脚注（Footer）

跨文件、行为变更、架构决策时建议写正文，说明 为什么改（而非重复改了什么）。

脚注常用键：

Refs: #123
Closes: #456
Reviewed-by: Alice <alice@example.com>
Co-authored-by: Bob <bob@example.com>
Signed-off-by: Carol <carol@example.com>    # DCO 场景

完整示例

fix(session): extend idle timeout for mobile clients

Mobile WebView resets activity timestamps inconsistently.
Increase idle timeout from 15m to 30m for mobile user agents only.

Closes: #789

5.6 禁止的 Commit Message

update
fix bug
WIP
temp
misc changes
asdf

5.7 Merge / Squash 策略

策略	适用	主干历史
Squash merge	功能分支多而杂的 WIP 提交	线性，一 PR 一 commit
Rebase merge	提交历史已整洁	线性，保留多个语义 commit
Merge commit	需保留分支拓扑	有 merge 节点

推荐： 短期分支合入 main/develop 时优先 Squash merge；Squash 后的标题应是一条符合 Conventional Commits 的 message，正文可汇总 PR 描述。

---

6. 分支与 Commit 类型对照

分支前缀	推荐 Commit 类型	典型合入目标
feature/*	feat	develop / main
fix/*、bugfix/*	fix	develop
hotfix/*	fix	main + develop
release/*	chore（版本 bump）	main + develop
refactor/*	refactor	develop
chore/*	chore、build、ci	develop
docs/*	docs	develop

---

7. 分支生命周期

创建 ──► 开发（与目标分支同步）──► PR 评审 ──► CI 通过 ──► 合入 ──► 删除远程分支

阶段	要求
创建	从最新的目标长期分支拉取；命名符合 §3
开发	定期 rebase 或 merge 目标分支，减少冲突；小步提交、语义清晰
评审	PR 标题遵循 Conventional Commits；关联 Issue；描述影响范围与测试方式
合入	CI 绿 + 至少 1 人 Approve（团队可规定 2 人）
清理	合入后 24～48h 内删除远程短期分支

分支存活期建议

分支类型	建议最长存活
feature/*	≤ 2 周
fix/*	≤ 3 天
hotfix/*	≤ 24 小时
release/*	至发布完成
experiment/*	≤ 1 周（过期即删）

---

8. 快速对照表

场景	从哪拉	合入哪	分支名示例
新功能（Git Flow）	develop	develop	feature/oauth2-login
新功能（GitHub Flow）	main	main	feature/oauth2-login
开发期 Bug	develop	develop	fix/session-expiry
生产热修	main	main + develop	hotfix/payment-timeout
版本发布	develop	main + Tag	release/1.4.0
依赖升级	develop	develop	chore/upgrade-deps
技术验证	develop	不合 main，转 feature	experiment/graphql-poc

---

9. Pull Request 标题规范

PR 标题应与合入后的 commit message 一致，推荐直接使用 Conventional Commits 格式：

feat(auth): add OAuth2 authorization code flow
fix(cart): prevent duplicate item on rapid click

关联 Issue 可在 PR 描述或脚注中声明 Closes #123，而非写入分支名。

---

10. 工具与自动化建议

工具	用途
commitlint	校验 commit message
husky	Git hooks 触发 lint/test
semantic-release	按 commit 自动 bump 版本、发 Tag、生成 CHANGELOG
release-please	Google 风格自动化发布
Branch protection rules	强制 PR、CI、Review

pre-commit 示例（commitlint）

{
  "extends": ["@commitlint/config-conventional"]
}

---

11. 修订记录

版本	日期	说明
2.0	2026-07-10	重写为业界通用规范：Conventional Commits、SemVer、Git Flow/GitHub Flow，去除项目特定命名
1.0	—	项目定制版（已 supersede）

---

附录 A：Conventional Commits 完整类型速查

feat     → 新功能
fix      → Bug 修复
docs     → 文档
style    → 代码格式（不影响含义）
refactor → 重构
perf     → 性能
test     → 测试
build    → 构建/依赖
ci       → 持续集成
chore    → 杂项维护
revert   → 回滚

附录 B：SemVer 升级规则摘要

变更性质	版本段	示例
破坏性 API/行为变更	MAJOR	1.4.0 → 2.0.0
向后兼容的新功能	MINOR	1.4.0 → 1.5.0
向后兼容的 Bug 修复	PATCH	1.4.0 → 1.4.1

附录 C：参考链接

• Conventional Commits
• Semantic Versioning 2.0.0
• A successful Git branching model (Git Flow)
• GitHub Flow
• Trunk Based Development
• Angular Commit Message Guidelines