分支命名方案概述

面向小型移动应用团队，基于 Git Flow 工作流程，提供一套简洁、可扩展、与后端 v2 接口对齐的分支命名规范。方案强调：

• 使用标准 Git Flow 长期分支：main、develop
• 统一短前缀：feature、bugfix、release、hotfix、support（可选）
• 以平台范围（ios｜android｜shared）+领域主题（离线下载、增量更新、断点续传、磁盘配额、国际化）构成主体
• 通过后缀标识接口对齐（v2），并可附带任务编号（如 map-123）
• 保持名称简短、可读、无歧义，符合 Git 技术限制

命名结构详细说明

• 总体格式：<前缀>/<平台>-<领域>-<细节>[-v2][-<任务ID>]
• 分隔符：
  • 斜杠 /：分隔前缀与主体
  • 连字符 -：分隔主体各组成部分
  • 点 .：仅用于版本号（如 1.0.0、rc.1）
• 字符集与大小写：
  • 小写字母 a–z、数字 0–9、连字符 -、斜杠 /、点 .
  • 禁止空格、中文、特殊字符（~, ^, :, ?, *, [, ], @, # 等）
• 组件说明：
  1. 前缀（必选）
     • feature：新功能开发（默认）
     • bugfix：非紧急缺陷修复（合并到 develop）
     • release：发布准备分支（从 develop 分出）
     • hotfix：紧急线上缺陷修复（从 main 分出）
     • support：维护旧版（可选，仅需长期维护时）
  2. 平台（必选）
     • ios、android、shared（跨平台或通用逻辑）
  3. 领域（必选，统一词根）
     • offline-dl（离线下载）
     • delta-update（增量更新）
     • resume（断点续传）
     • quota（磁盘配额）
     • i18n（国际化）
  4. 细节（必选，简短明确）
     • 如 manager, worker, ui, error-msg, storage, api-client
  5. 接口对齐（可选但推荐）
     • -v2：涉及或依赖后端 v2 接口时必须添加
  6. 任务ID（可选但推荐）
     • 统一小写，如 map-123（Jira/Tapd/自定义 ID 转小写）

各组成部分的使用规则

• 长期分支
  • main：稳定发布历史，只接受 release 和 hotfix 合并
  • develop：集成分支，接受 feature、bugfix 合并
• 版本与发布
  • 发布分支命名：release/<app-semver>，如 release/1.0.0
  • 预发布标记：在 release 分支打标签 v1.0.0-rc.1、v1.0.0-rc.2 等
  • 正式发布：合并到 main，打标签 v1.0.0
• 接口对齐
  • 凡与后端 v2 交互或受其协议影响的分支，主体末尾必须加 -v2
  • 纯客户端 UI/文案调整，可不加 -v2
• 命名长度与可读性
  • 建议 ≤ 60 字符，避免冗长细节；主题词不超过 3 段（领域+细节最多 3 个连字符）
• Git 技术限制校验
  • 不以 -、. 开头或结尾；不以 / 结尾；不出现 .. 或连续多 /
• 合并策略（与 Git Flow 对齐）
  • feature/bugfix → develop（Squash 合并或保留清晰历史）
  • release → main（并回合 develop 同步版本号变更）
  • hotfix → main 与 develop（双向合并，防止漂移）

具体应用场景示例

• 功能开发（与后端 v2 对齐）
  • feature/ios-offline-dl-manager-v2
  • feature/android-delta-update-worker-v2
  • feature/shared-resume-api-client-v2
  • feature/shared-quota-storage-v2
  • feature/shared-i18n-error-msg-v2
• 缺陷修复（非紧急）
  • bugfix/ios-offline-dl-retry-logic-map-238
  • bugfix/android-quota-ui-overflow-map-247
• 紧急修复（发布后）
  • hotfix/1.0.0-android-resume-crash
  • hotfix/1.0.0-ios-i18n-null-locale
• 发布分支与标签（春节前一次性发布）
  • 创建：release/1.0.0
  • 预发布标签：v1.0.0-rc.1、v1.0.0-rc.2
  • 正式标签：v1.0.0
• 跨平台共享模块
  • feature/shared-offline-dl-chunking-v2
  • feature/shared-delta-update-merger-v2
• 文案与本地化
  • feature/shared-i18n-dl-hint-v2
  • bugfix/shared-i18n-android-rtl-map-312

实施建议和注意事项

• 命名校验（推荐在仓库层面启用）
  • 可使用以下正则进行预接收钩子校验（示例）：
    • Feature/Bugfix：^(feature|bugfix)/(ios|android|shared)-[a-z0-9]+(-[a-z0-9]+){1,3}(-v2)?(-[a-z]+-[0-9]+)?$
    • Release：^release/[0-9]+\.[0-9]+\.[0-9]+$
    • Hotfix：^hotfix/[0-9]+\.[0-9]+\.[0-9]+-[a-z0-9-]+$
  • 说明：根据团队需要精简或放宽细节段数量
• 版本策略
  • 采用 SemVer：首次“一次性发布”设为 1.0.0
  • 与后端接口映射：在 CHANGELOG 或 RELEASE NOTES 中注明“依赖后端 v2”
• 分支生命周期
  • feature/bugfix 分支在合并后删除；release/hotfix 合并完成后删除
• 提交流程
  • PR 标题采用同名分支；描述中列出范围（平台、领域、接口版本）、测试要点与风险
• 团队约定（小型团队优化）
  • 平台值仅用 ios、android、shared 三类，避免出现模块名作为平台段
  • 领域词固定五类：offline-dl、delta-update、resume、quota、i18n
  • 细节段控制在 1–2 个词，如 ui、manager、worker、storage、api-client
• 辅助自动化
  • 设置分支保护：main 和 develop 禁止直接 push、要求 PR 审核
  • CI 根据前缀路由流程：feature/bugfix 运行单元与集成；release 增加打包与签名；hotfix 最小回归集
• 风险与约束
  • 避免在分支名中使用日期或节日标识（如 spring-festival），使用版本号统一标记发布窗口
  • 不在分支名混入环境（staging、prod），环境由部署流水线控制

此规范在不改变 Git Flow 的前提下，最小化新增约定（仅平台、领域、接口版本与任务ID），保证移动端双平台协作、后端 v2 对齐、春节前一次性发布的可操作性与一致性。

分支命名方案概述

面向：前端 UI 组件库/框架，新增可访问性（ARIA、键盘导航、高对比度主题）能力；中型团队；GitLab Flow；需要版本化文档与 CI 自动发布预览包。

目标：在 GitLab Flow 框架下，提供简洁一致的分支命名，覆盖工作分支、发布/热修分支、环境分支与文档版本分支，确保：

• 分支名可读、可检索、可扩展
• 与 Issue/MR 流程无缝对齐
• 方便 CI 生成稳定的 preview 包标识（依赖 CI_COMMIT_REF_SLUG）
• 支持版本化文档的维护与补丁修复

核心思想：

• 主干即生产（main），采用基于 Issue 的短期工作分支
• 以类型前缀（feat/fix/docs/...）+ 领域/组件范围（scope）+ Issue 编号为主骨架
• 发布/热修使用 release/x.y 与 hotfix/x.y.z
• 环境分支 env/staging 用于预发布
• 文档版本分支 docs/vx.y + docs-fix/vx.y-... 支撑历史版本文档维护

命名结构详细说明

通用规范

• 字符集：小写字母、数字、连字符（-）与分隔斜杠（/）
• 不允许：空格、#、@、?、&、%、连续双连字符（--）、结尾为斜杠
• 分隔符：目录级使用斜杠（/），同级描述使用连字符（-）
• 建议长度：不超过 60 个字符（避免 CI 产物标签过长）
• 必须包含 Issue ID（i<数字>）以便追踪；在 MR 描述中仍需写明 Closes #

1. 工作分支（功能/修复/文档/重构等）

• 结构：type/scope/i-short-desc
• type（固定集合）：
  • feat | fix | docs | refactor | perf | test | chore | ci | build
• scope（领域/模块）建议：
  • a11y（可访问性跨域任务）
  • ui-（组件粒度：如 ui-button, ui-modal, ui-combobox, ui-tabs, ui-slider, ui-tooltip）
  • theme（主题/对比度相关）
  • docs-site（文档站点工程）
  • infra（基础设施，如打包、lint、预发布流程）
  • 多域时优先选择主域：如 a11y 优先于 ui
• short-desc：3–6 个英文短词，短横线连接，描述性强，如 aria-labels、focus-trap、roving-tabindex、high-contrast

示例：feat/a11y/i321-aria-labels-for-button

2. 发布分支（冻结稳定期，准备发版）

• 结构：release/x.y
• 用途：在 x.y 次版本周期冻结，合并修复，准备打 tag（vX.Y.Z）
• 来源：从 main 拉出

3. 热修分支（生产紧急修复）

• 结构：hotfix/x.y.z-short-desc
• 来源：从 main 拉出，修复后合并回 main，并 cherry-pick 到对应 release/x.y（如需）

4. 环境分支（GitLab Flow 环境部署）

• 结构：env/staging（可扩展 env/qa）
• main 即生产（production），env/staging 持续从 main（或指定 release）同步，用于预发布

5. 文档版本与修复分支

• 冻结分支：docs/vx.y（用于快照 vX.Y 文档）
• 补丁分支：docs-fix/vx.y-short-desc（基于 docs/vx.y 进行文档问题修复）

各组成部分的使用规则

命名约束

• 全部小写；仅使用 [a-z0-9-] 与分隔斜杠
• 必含 Issue ID：i<数字>，例如 i321；避免使用 #321（Git 会误解析）
• short-desc 使用明确领域词汇，避免模糊词（update、change、temp）

工作分支规则

• 分支来源：最新的 main 或对应 release/x.y（在发布冻结期做修复时）
• 可访问性任务：
  • 新增能力：feat/a11y/... 或 feat/ui-/...
  • 修复缺陷：fix/a11y/... 或 fix/ui-/...
  • 主题对比度：feat/theme/... 或 fix/theme/...
• 文档：
  • 伴随功能的文档改动，仍在功能分支内完成（推荐）
  • 仅文档修复：docs/docs-site/i-

发布/热修规则

• release/x.y：进入稳定期后，仅允许修复（fix/chore/docs）合并
• hotfix/x.y.z-...：紧急修复，合并 main 后按需回移至最近的 release/x.y 和文档分支

文档版本规则

• 每个次版本发布（vX.Y.0）后，从 main 创建 docs/vx.y
• 对历史版本文档的修复，从 docs-fix/vx.y-... 合并回 docs/vx.y
• 新版本功能的文档，随功能分支合并回 main，并在发版时同步到 docs/vx.y

CI 预览包规则（命名友好性）

• 所有工作分支（type/...）均触发预览包发布
• 预览包标签建议使用 CI_COMMIT_REF_SLUG（GitLab 自动安全化的分支名）
  • npm dist-tag 示例：preview-${CI_COMMIT_REF_SLUG}
  • 预发布版本号示例：X.Y.Z-rc.${CI_PIPELINE_IID} 或 0.0.0-${CI_COMMIT_REF_SLUG}.${CI_PIPELINE_IID}
• 排除 release/、hotfix/、docs/、docs-fix/、env/* 分支触发预览（可在 CI 规则中限制）

保护规则与正则校验

• 保护分支：main、release/、docs/v、env/staging
• 分支命名校验（GitLab Push Rules / CI 预检）：
  • 工作分支： ^(feat|fix|docs|refactor|perf|test|chore|ci|build)/[a-z0-9-]+/i[0-9]+-[a-z0-9-]+$
  • 发布分支： ^release/\d+.\d+$
  • 热修分支： ^hotfix/\d+.\d+.\d+(?:-[a-z0-9-]+)?$
  • 环境分支： ^env/(staging|qa)$
  • 文档版本与修复： ^docs/v\d+.\d+$ 与 ^docs-fix/v\d+.\d+-[a-z0-9-]+$

具体应用场景示例

可访问性新增与修复

• 新增：feat/a11y/i321-aria-labels-for-button
• 键盘导航（Roving Tabindex）：feat/ui-listbox/i338-roving-tabindex
• 高对比度主题：feat/theme/i352-high-contrast-dark
• 焦点陷阱修复（Modal）：fix/a11y/i401-focus-trap-in-modal
• Tabs 可访问性规范补充：docs/docs-site/i360-a11y-tabs-guidelines

CI 预览包（由分支名生成稳定 slug）

• 分支：feat/a11y/i321-aria-labels-for-button
• GitLab 变量：CI_COMMIT_REF_SLUG=feat-a11y-i321-aria-labels-for-button
• 预览包 dist-tag：preview-feat-a11y-i321-aria-labels-for-button
• 预发布版本号（示例）：2.1.0-rc.12345 或 0.0.0-feat-a11y-i321-aria-labels-for-button.12345

发布与热修

• 冻结 2.1 次版本：release/2.1
• 修复合并到发布分支：fix/ui-combobox/i417-highlight-bug
  • 分支名：fix/ui-combobox/i417-highlight-bug
  • 目标分支：release/2.1
• 打 Tag：v2.1.0
• 生产回归热修：hotfix/2.1.3-contrast-regression
  • 从 main 切出，修复并合回 main；再 cherry-pick 至 release/2.1

文档版本化

• 发布 v2.1.0 后冻结文档：docs/v2.1
• 回补 v2.1 文档错误链接：docs-fix/v2.1-fix-broken-links
• 新功能文档（随开发）：docs/docs-site/i450-a11y-keyboard-nav

环境分支

• 预发布部署：env/staging
  • 从 main 定期合入（或由 CI 自动快进）
  • 用于 QA 与可访问性回归测试

实施建议和注意事项

落地步骤

• 在 GitLab 设置保护分支：main、release/、docs/v、env/staging（仅允许维护者推送）
• 启用 Push Rules 或在 CI 中添加命名正则校验，拒绝不合规分支
• 在 MR 模板中要求：
  • 标题以类型开头并引用分支短描述
  • 描述中包含 Closes #，并说明变更范围（组件、A11y 影响、Docs 更新）
• CI 规则：
  • 仅对工作分支（type/*）发布 preview 包；release/hotfix 合并时发布正式版本
  • 使用 CI_COMMIT_REF_SLUG 构造唯一且稳定的 dist-tag
  • 对 docs/vx.y 与 docs-fix/vx.y-* 分支仅构建文档站点，不发布包
• 代码所有者（CODEOWNERS）：
  • a11y 相关更改（包含 scope a11y 或 theme）自动请求指定评审人
• 约定清单：
  • 统一组件命名表（button、modal、combobox、listbox、tabs、slider、tooltip、link...）
  • A11y 关键术语表（aria-labels、roving-tabindex、focus-trap、skip-links、sr-only、landmarks、contrast）

注意事项

• 始终在分支名中包含 Issue ID（i），但不要依赖其自动链接；在 MR 中使用 Closes #
• 避免在分支名中使用下划线、点号或非 ASCII 字符，确保跨工具兼容性
• 多组件大改动尽量拆分为多个小分支；确需合并管理时使用同一 Issue Epic 追踪
• 当 release/x.y 存在时，修复优先针对 release/x.y，再合并回 main 保持一致

此方案遵循 GitLab Flow、语义化版本发布与行业通用实践，既满足可访问性场景的清晰表达，又便于 CI 生成稳定的预览包标签与后续扩展维护。