branch-strategy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Branch Strategy

分支策略

Branch Naming Conventions

分支命名规范

Every branch name must follow a structured prefix convention. This keeps the repository navigable, enables CI/CD automation, and makes intent immediately clear.

所有分支名称必须遵循结构化前缀约定。这能让仓库更易导航，支持CI/CD自动化，并且能直接体现分支用途。

Required Prefixes

必填前缀

Prefix	Purpose	Example
`feature/`	New functionality or capability	`feature/user-avatar-upload`
`fix/`	Bug fixes for existing behavior	`fix/login-redirect-loop`
`hotfix/`	Urgent production fixes	`hotfix/payment-null-pointer`
`release/`	Release preparation and stabilization	`release/2.4.0`
`chore/`	Maintenance, dependencies, tooling	`chore/upgrade-eslint-9`
`docs/`	Documentation-only changes	`docs/api-authentication-guide`
`refactor/`	Code restructuring without behavior change	`refactor/extract-billing-service`
`test/`	Adding or fixing tests only	`test/payment-edge-cases`
`experiment/`	Exploratory work, not intended for merge	`experiment/graphql-federation`

前缀	用途	示例
`feature/`	新增功能或能力	`feature/user-avatar-upload`
`fix/`	修复现有功能的Bug	`fix/login-redirect-loop`
`hotfix/`	紧急生产环境修复	`hotfix/payment-null-pointer`
`release/`	发布准备与稳定性优化	`release/2.4.0`
`chore/`	维护、依赖更新、工具调整	`chore/upgrade-eslint-9`
`docs/`	仅修改文档	`docs/api-authentication-guide`
`refactor/`	代码重构（不改变功能）	`refactor/extract-billing-service`
`test/`	仅添加或修复测试	`test/payment-edge-cases`
`experiment/`	探索性工作，不用于合并	`experiment/graphql-federation`

Naming Rules

命名规则

Use lowercase with hyphens as separators:

feature/add-user-search

not

feature/Add_User_Search

Keep names concise but descriptive:

fix/cart-total

not

fix/the-bug-where-cart-total-shows-wrong-amount

Include a ticket or issue number when one exists:
```
feature/PROJ-1234-user-avatar-upload
```

Never use personal names:

feature/search-api

not

feature/anthonys-search-work

Avoid generic names:
```
fix/login-redirect-loop
```
not
```
fix/bug
```
or
```
fix/stuff
```
Maximum length: aim for under 50 characters after the prefix

使用小写字母，连字符分隔：

feature/add-user-search

而非

feature/Add_User_Search

名称需简洁且具描述性：

fix/cart-total

而非

fix/the-bug-where-cart-total-shows-wrong-amount

若存在工单或问题编号，需包含在内：
```
feature/PROJ-1234-user-avatar-upload
```

禁止使用个人姓名：

feature/search-api

而非

feature/anthonys-search-work

避免通用名称：
```
fix/login-redirect-loop
```
而非
```
fix/bug
```
或
```
fix/stuff
```
长度限制：前缀后的内容尽量控制在50字符以内

Ticket Number Placement

工单编号位置

When integrating with issue trackers, place the ticket number immediately after the prefix:

feature/PROJ-1234-user-avatar-upload
fix/GH-567-null-pointer-on-empty-cart
hotfix/INC-89-payment-gateway-timeout

This enables automated linking between branches, PRs, and issues.

与问题追踪工具集成时，需将工单编号紧跟在前缀之后：

feature/PROJ-1234-user-avatar-upload
fix/GH-567-null-pointer-on-empty-cart
hotfix/INC-89-payment-gateway-timeout

这能实现分支、PR和问题之间的自动关联。

Branching Models

分支模型

Trunk-Based Development

主干开发（Trunk-Based Development）

The simplest model. All developers work on short-lived branches off

main

and merge back frequently.

main ─────●─────●─────●─────●─────●─────●─────
           \   /       \   /       \   /
            ●─●         ●─●         ●
          (feature)   (fix)     (feature)

When to Use Trunk-Based Development:

Teams with strong CI/CD pipelines and automated testing
Continuous deployment environments
Small to medium teams (2-15 developers)
Products that ship continuously (SaaS, web applications)
Teams practicing feature flags for incomplete work

Rules:

Branches live no longer than 1-2 days
Every commit to
```
main
```
must pass all tests
Use feature flags to hide incomplete functionality
No long-lived branches except
```
main
```
Deploy from
```
main
```
on every merge (or at minimum daily)
Keep changes small and incremental

Branch Lifecycle:

bash

undefined

最简单的模型。所有开发者基于

main

创建短期分支，并频繁合并回主干。

main ─────●─────●─────●─────●─────●─────●─────
           \   /       \   /       \   /
            ●─●         ●─●         ●
          (feature)   (fix)     (feature)

适用场景：

拥有完善CI/CD流水线和自动化测试的团队
持续部署环境
中小型团队（2-15名开发者）
持续发布的产品（SaaS、Web应用）
使用功能标记隐藏未完成工作的团队

规则：

分支生命周期不超过1-2天
所有提交到
```
main
```
的代码必须通过全部测试
使用功能标记隐藏未完成功能
除
```
main
```
外无长期分支
每次合并后从
```
main
```
部署（至少每日部署）
保持变更小而增量式

分支生命周期：

bash

undefined

Create branch from main

从main创建分支

git checkout main && git pull git checkout -b feature/PROJ-123-add-search

Work in small increments, commit frequently

小步迭代，频繁提交

git add -p && git commit -m "Add search index configuration" git add -p && git commit -m "Implement basic search query endpoint"

Rebase onto main before merging

合并前基于main变基

git fetch origin && git rebase origin/main

Merge via PR (squash or merge commit per team convention)

通过PR合并（按团队约定使用 squash 或合并提交）

Delete branch immediately after merge

合并后立即删除分支

undefined

undefined

Git Flow

A structured model with multiple long-lived branches for teams that need formal release management.

main     ─────●──────────────────●──────────────
              |                  |
develop  ─────●────●────●────●───●────●─────────
               \  / \  /    |       /
feature         ●●   ●●   release ●
                            \   /
                             ●─●

When to Use Git Flow:

Products with scheduled releases (mobile apps, installed software)
Teams that maintain multiple versions simultaneously
Regulated industries requiring release audit trails
Larger teams (15+ developers) needing coordination
Projects with dedicated QA phases

Branch Structure:

Branch	Lifetime	Merges Into	Purpose
`main`	Permanent	--	Production-ready code, tagged releases
`develop`	Permanent	`main` (via release)	Integration branch for features
`feature/*`	Temporary	`develop`	New work in progress
`release/*`	Temporary	`main` and `develop`	Release stabilization
`hotfix/*`	Temporary	`main` and `develop`	Urgent production fixes

Release Workflow:

bash

undefined

结构化模型，包含多个长期分支，适用于需要正式发布管理的团队。

main     ─────●──────────────────●──────────────
              |                  |
develop  ─────●────●────●────●───●────●─────────
               \  / \  /    |       /
feature         ●●   ●●   release ●
                            \   /
                             ●─●

适用场景：

定期发布的产品（移动应用、安装类软件）
同时维护多个版本的团队
需要发布审计追踪的受监管行业
大型团队（15+名开发者）需要协调工作
有专门QA阶段的项目

分支结构：

分支	生命周期	合并目标	用途
`main`	永久	--	生产就绪代码，带标签的发布版本
`develop`	永久	`main` （通过发布分支）	功能集成分支
`feature/*`	临时	`develop`	进行中的新工作
`release/*`	临时	`main` 和 `develop`	发布稳定性优化
`hotfix/*`	临时	`main` 和 `develop`	紧急生产环境修复

发布工作流：

bash

undefined

1. Create release branch from develop

1. 从develop创建发布分支

git checkout develop && git pull git checkout -b release/2.4.0

2. Only bug fixes, documentation, and release prep on this branch

2. 该分支仅允许Bug修复、文档更新和发布准备工作

No new features allowed

禁止添加新功能

3. When stable, merge to main and tag

3. 稳定后合并到main并打标签

git checkout main && git merge --no-ff release/2.4.0 git tag -a v2.4.0 -m "Release 2.4.0"

4. Back-merge to develop

4. 反向合并到develop

git checkout develop && git merge --no-ff release/2.4.0

5. Delete release branch

5. 删除发布分支

git branch -d release/2.4.0


**Hotfix Workflow:**

```bash

git branch -d release/2.4.0


**热修复工作流：**

```bash

1. Branch from main

1. 从main创建热修复分支

git checkout main && git pull git checkout -b hotfix/payment-null-pointer

2. Fix the issue, commit

2. 修复问题并提交

3. Merge to both main and develop

3. 合并到main和develop

git checkout main && git merge --no-ff hotfix/payment-null-pointer git tag -a v2.4.1 -m "Hotfix: payment null pointer" git checkout develop && git merge --no-ff hotfix/payment-null-pointer

4. Delete hotfix branch

4. 删除热修复分支

git branch -d hotfix/payment-null-pointer

undefined

git branch -d hotfix/payment-null-pointer

undefined

GitHub Flow

A simplified model that sits between trunk-based and Git Flow.

When to Use GitHub Flow:

Web applications with continuous deployment
Open source projects
Teams that want simplicity but still use pull requests
When Git Flow feels too heavy but you want PR-based review

Rules:

```
main
```
is always deployable
Branch from
```
main
```
for any work
Open a PR when you want feedback or are ready to merge
Merge to
```
main
```
after review and CI passes
Deploy immediately after merge

简化模型，介于主干开发和Git Flow之间。

适用场景：

持续部署的Web应用
开源项目
想要简洁性但仍使用Pull Request的团队
觉得Git Flow过于繁琐但需要基于PR的代码评审的团队

规则：

```
main
```
分支始终可部署
任何工作都基于
```
main
```
创建分支
需要反馈或准备合并时打开PR
评审通过且CI检查通过后合并到
```
main
```
合并后立即部署

Branch Protection Rules

分支保护规则

Recommended Protection for

main

main

分支推荐保护配置

yaml

branch_protection:
  main:
    required_reviews: 1           # At least one approval
    dismiss_stale_reviews: true   # Re-review after new pushes
    require_status_checks: true   # CI must pass
    required_checks:
      - build
      - test
      - lint
    restrict_pushes: true         # No direct pushes
    require_linear_history: true  # Squash or rebase only
    include_administrators: true  # Rules apply to everyone

yaml

branch_protection:
  main:
    required_reviews: 1           # 至少1次审批
    dismiss_stale_reviews: true   # 新推送后需重新评审
    require_status_checks: true   # 必须通过CI检查
    required_checks:
      - build
      - test
      - lint
    restrict_pushes: true         # 禁止直接推送
    require_linear_history: true  # 仅允许 squash 或变基
    include_administrators: true  # 规则适用于所有人

Protection by Branch Type

按分支类型设置保护规则

Rule	`main`	`develop`	`release/*`	`feature/*`
Require PR	Yes	Yes	Yes	No
Required reviewers	1-2	1	1-2	0
Require CI pass	Yes	Yes	Yes	Optional
Allow force push	No	No	No	Yes (owner)
Allow deletion	No	No	After merge	Yes
Require signed commits	Recommended	Optional	Optional	No

规则	`main`	`develop`	`release/*`	`feature/*`
要求PR	是	是	是	否
所需评审人数	1-2	1	1-2	0
要求通过CI	是	是	是	可选
允许强制推送	否	否	否	是（分支所有者）
允许删除	否	否	合并后	是
要求签名提交	推荐	可选	可选	否

Release Tagging and Semantic Versioning

发布标签与语义化版本（Semantic Versioning）

Semver Format

Semver格式

MAJOR.MINOR.PATCH
  |     |     |
  |     |     └── Bug fixes, no API changes
  |     └──────── New features, backward compatible
  └────────────── Breaking changes

MAJOR.MINOR.PATCH
  |     |     |
  |     |     └── Bug修复，无API变更
  |     └──────── 新增功能，向后兼容
  └────────────── 破坏性变更

When to Bump Each Number

版本号升级规则

MAJOR (breaking): Removing an API endpoint. Changing a response format. Renaming a public function. Dropping support for a platform.

MINOR (feature): Adding a new endpoint. Adding optional parameters. New configuration options. New UI features.

PATCH (fix): Bug fixes. Security patches. Performance improvements. Documentation corrections.

MAJOR（主版本号，破坏性变更）： 删除API接口、修改响应格式、重命名公共函数、移除平台支持。

MINOR（次版本号，功能新增）： 新增接口、添加可选参数、新增配置项、新增UI功能。

PATCH（修订号，Bug修复）： Bug修复、安全补丁、性能优化、文档修正。

Pre-release and Build Metadata

预发布与构建元数据

2.4.0-alpha.1      # Alpha pre-release
2.4.0-beta.2       # Beta pre-release
2.4.0-rc.1         # Release candidate
2.4.0+build.1234   # Build metadata (ignored in precedence)

2.4.0-alpha.1      # Alpha预发布版本
2.4.0-beta.2       # Beta预发布版本
2.4.0-rc.1         # 发布候选版本
2.4.0+build.1234   # 构建元数据（版本优先级中会被忽略）

Tagging Checklist

打标签检查清单

Creating Tags

创建标签

bash

undefined

bash

undefined

Annotated tag (preferred for releases)

带注释的标签（发布版本首选）

git tag -a v2.4.0 -m "Release 2.4.0: Add user search, fix cart totals"

Push tags to remote

将标签推送到远程仓库

git push origin v2.4.0

Or push all tags

或推送所有标签

git push origin --tags

undefined

git push origin --tags

undefined

Tag Naming Convention

标签命名规范

Always prefix with
```
v
```
:
```
v2.4.0
```
not
```
2.4.0
```
Match the version in your package files exactly
Use annotated tags (not lightweight) for releases

始终以
```
v
```
为前缀：
```
v2.4.0
```
而非
```
2.4.0
```
与包文件中的版本号完全一致
发布版本使用带注释的标签（而非轻量标签）

Feature Branch Lifecycle

功能分支生命周期

Standard Lifecycle

标准生命周期

1. CREATE    ──  Branch from main/develop with proper prefix
2. DEVELOP   ──  Commit regularly, push daily
3. SYNC      ──  Rebase/merge from upstream regularly
4. REVIEW    ──  Open PR, request review
5. REVISE    ──  Address feedback, push updates
6. MERGE     ──  Squash or merge commit per convention
7. CLEANUP   ──  Delete branch locally and remotely

1. 创建    ──  基于main/develop创建分支，使用正确前缀
2. 开发   ──  定期提交，每日推送
3. 同步    ──  定期从上游分支变基/合并
4. 评审    ──  打开PR，请求评审
5. 修改    ──  处理反馈，推送更新
6. 合并    ──  按约定使用squash或合并提交
7. 清理    ──  本地和远程仓库都删除分支

Keeping Branches Current

保持分支同步

bash

undefined

bash

undefined

Option A: Rebase (cleaner history, use for personal branches)

选项A：变基（历史更整洁，适用于个人分支）

git fetch origin git rebase origin/main

Option B: Merge (preserves history, use for shared branches)

选项B：合并（保留历史，适用于共享分支）

git fetch origin git merge origin/main

undefined

git fetch origin git merge origin/main

undefined

Stale Branch Policy

stale分支策略

Branches with no commits for 14+ days should be reviewed
Branches with no commits for 30+ days should be closed or archived
Automate stale branch notifications via CI/CD

14天无提交的分支需进行评审
30天无提交的分支应关闭或归档
通过CI/CD自动化发送stale分支通知

Decision Guide

决策指南

Use this flowchart to choose your branching model:

Do you deploy continuously to production?
├── Yes: Do you need PR-based code review?
│   ├── Yes ──► GitHub Flow
│   └── No  ──► Trunk-Based Development
└── No: Do you maintain multiple release versions?
    ├── Yes ──► Git Flow
    └── No: Do you have scheduled release cycles?
        ├── Yes ──► Git Flow (simplified)
        └── No  ──► GitHub Flow

使用以下流程图选择分支模型：

是否持续部署到生产环境？
├── 是：是否需要基于PR的代码评审？
│   ├── 是 ──► GitHub Flow
│   └── 否  ──► 主干开发（Trunk-Based Development）
└── 否：是否维护多个发布版本？
    ├── 是 ──► Git Flow
    └── 否：是否有固定发布周期？
        ├── 是 ──► Git Flow（简化版）
        └── 否  ──► GitHub Flow

Anti-Patterns to Avoid

需避免的反模式

Long-lived feature branches -- Branches open for weeks accumulate merge conflicts and drift from main. Break work into smaller increments.
Merging main into feature branches repeatedly -- Creates a tangled history. Prefer rebasing for personal branches.
Skipping branch protection -- Even solo developers benefit from CI checks on main.
Inconsistent naming -- Mixed conventions make automation impossible. Enforce via CI hooks.
Forgetting to delete merged branches -- Stale branches clutter the repository. Configure auto-delete on merge.
Direct commits to main -- Bypasses review and CI. Always use PRs except for truly trivial changes on solo projects.
Release branches without version bumps -- Every release branch must update version numbers as its first commit.
Cherry-picking without tracking -- If you cherry-pick a fix to multiple branches, document which branches received the fix.

长期存在的功能分支 -- 开放数周的分支会积累大量合并冲突，与主干代码脱节。应将工作拆分为更小的增量任务。
反复将main合并到功能分支 -- 会导致历史记录混乱。个人分支优先使用变基。
跳过分支保护 -- 即使是独立开发者，主干分支的CI检查也能带来收益。
命名不一致 -- 混合规范会让自动化无法实现。通过CI钩子强制规范。
忘记删除已合并分支 -- stale分支会使仓库杂乱。配置合并后自动删除分支。
直接提交到main -- 绕过评审和CI检查。除了独立项目中真正微不足道的变更，始终使用PR。
发布分支未更新版本号 -- 每个发布分支的第一个提交必须更新版本号。
无追踪的樱桃拣选 -- 若将修复樱桃拣选到多个分支，需记录哪些分支已应用该修复。

branch-strategy

Original

Translation

Branch Strategy

分支策略

Branch Naming Conventions

分支命名规范

Required Prefixes

必填前缀

Naming Rules

命名规则

Ticket Number Placement

工单编号位置

Branching Models

分支模型

Trunk-Based Development

主干开发（Trunk-Based Development）

Create branch from main

从main创建分支

Work in small increments, commit frequently

小步迭代，频繁提交

Rebase onto main before merging

合并前基于main变基

Merge via PR (squash or merge commit per team convention)

通过PR合并（按团队约定使用 squash 或合并提交）

Delete branch immediately after merge

合并后立即删除分支

Git Flow

Git Flow

1. Create release branch from develop

1. 从develop创建发布分支

2. Only bug fixes, documentation, and release prep on this branch

2. 该分支仅允许Bug修复、文档更新和发布准备工作

No new features allowed

禁止添加新功能

3. When stable, merge to main and tag

3. 稳定后合并到main并打标签

4. Back-merge to develop

4. 反向合并到develop

5. Delete release branch

5. 删除发布分支

1. Branch from main

1. 从main创建热修复分支

2. Fix the issue, commit

2. 修复问题并提交

3. Merge to both main and develop

3. 合并到main和develop

4. Delete hotfix branch

4. 删除热修复分支

GitHub Flow

GitHub Flow

Branch Protection Rules

分支保护规则

Recommended Protection for main

main分支推荐保护配置

Protection by Branch Type

按分支类型设置保护规则

Release Tagging and Semantic Versioning

发布标签与语义化版本（Semantic Versioning）

Semver Format

Semver格式

When to Bump Each Number

版本号升级规则

Pre-release and Build Metadata

预发布与构建元数据

Tagging Checklist

打标签检查清单

Creating Tags

创建标签

Annotated tag (preferred for releases)

带注释的标签（发布版本首选）

Push tags to remote

将标签推送到远程仓库

Or push all tags

或推送所有标签

Tag Naming Convention

标签命名规范

Feature Branch Lifecycle

功能分支生命周期

Standard Lifecycle

Recommended Protection for
`main`

`main`
分支推荐保护配置