Git 分支与提交命名规范

版本2.0适用范围通用软件工程团队与具体项目/产品线无关参考标准Conventional Commits、Semantic Versioning、Git Flow、GitHub Flow1. 总则1.1 命名基本原则规则说明全小写分支名、标签名一律使用小写字母与数字连字符分隔多词之间用-kebab-case不使用_或驼峰斜杠分层短期分支使用类型/描述形式便于分组与权限管理语义清晰名称应体现变更类型 变更意图避免fix、temp、test等无意义命名短而准描述部分建议 25 个英文单词总长不超过 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、单主干mainGit Flow版本化发布、需发布冻结期maindevelopTrunk-Based Development高频集成、强 CI/CDmain短期分支 ≤ 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 Flowmaster生产基线历史命名与main等价新仓库优先使用maindevelop集成开发主干日常开发集成分支功能/fix 分支的默认合入目标Git Flow约束长期分支禁止--force推送合入前须通过 CI 与 Code Review不在长期分支上直接开发紧急 hotfix 除外3. 短期分支Short-lived Branches从对应的长期分支拉取完成工作后通过 PR/MR 合入合入后删除远程分支。3.1 功能分支 —feature/用于新功能、需求迭代、非紧急重构。feature/简短描述 feature/issue-id-简短描述 # 关联 Issue 时推荐字段规则示例简短描述动宾或名词短语kebab-caseoauth2-login、export-csvissue-id可选与 Tracker 一致123、PROJ-456示例feature/oauth2-login feature/123-export-user-report feature/shopping-cart-checkout工作流Git Flowdevelop ──► feature/oauth2-login ──► PR ──► develop3.2 缺陷修复分支 —fix/或bugfix/用于开发/测试阶段发现的缺陷修复非生产紧急问题。fix/简短描述 fix/issue-id-简短描述示例fix/null-pointer-on-logout fix/456-email-validation-regexfix/与bugfix/语义相同团队择一统一Conventional Commits 中对应类型均为fix。与hotfix/的区别见 §3.3。3.3 热修复分支 —hotfix/用于生产环境紧急修复。从main或master拉取修复后合入main并回合并入developGit Flow。hotfix/简短描述 hotfix/版本号-简短描述 # 多热修并行时可加版本号示例hotfix/payment-gateway-timeout hotfix/1.2.1-session-leak工作流Git Flowmain ──► hotfix/payment-gateway-timeout ──► PR ──► main └──► PR ──► develop3.4 发布分支 —release/用于发布前版本冻结、CHANGELOG 整理、版本号 bump、回归测试。从develop拉取完成后合入main并打 Tag再回合并入develop。release/主版本.次版本.修订号遵循 Semantic VersioningMAJOR.MINOR.PATCH示例release/1.4.0 release/2.0.0-rc.1 # 预发布版本可选3.5 重构分支 —refactor/不改变外部可观测行为的大规模结构调整。refactor/简短描述示例refactor/extract-payment-service refactor/migrate-to-vitest3.6 工程化分支 —chore/构建脚本、依赖升级、CI 配置、工具链变更等非业务代码。chore/简短描述示例chore/upgrade-node-20 chore/add-dependabot-config3.7 文档分支 —docs/仅文档变更若与功能同 PR 可不必单独建分支。docs/简短描述示例docs/api-authentication-guide docs/update-contributing3.8 实验分支 —experiment/或spike/概念验证、技术调研不得直接合入main结论沉淀后以feature/或refactor/重新提交。experiment/简短描述3.9 禁止的分支命名模式模式原因dev-用户名、tmp-*个人临时分支易泄漏、难追溯纯数字、纯日期无语义含空格或特殊字符跨平台/Git 工具兼容性问题与长期分支同名前缀混淆如main-backup、develop-old4. 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.0build.20240710 # 构建元数据可选约束Tag 仅打在main或发布 commit上禁止移动已推送的 Tag若需修正使用新的 patch 版本号Annotated Tag 优于 Lightweight Tag含作者、日期、说明git tag -a v1.4.0 -m Release 1.4.0: OAuth2 login, CSV export5. 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 setup5.2 类型Type类型含义语义化版本影响feat新功能MINOR ↑fix缺陷修复PATCH ↑docs仅文档—style格式空格、分号等不影响逻辑—refactor重构非 feat/fix—perf性能优化PATCH ↑部分工具test测试增删改—build构建系统或外部依赖—ciCI 配置与脚本—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 aliceexample.com Co-authored-by: Bob bobexample.com Signed-off-by: Carol carolexample.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: #7895.6 禁止的 Commit Messageupdate fix bug WIP temp misc changes asdf5.7 Merge / Squash 策略策略适用主干历史Squash merge功能分支多而杂的 WIP 提交线性一 PR 一 commitRebase merge提交历史已整洁线性保留多个语义 commitMerge commit需保留分支拓扑有 merge 节点推荐短期分支合入main/develop时优先Squash mergeSquash 后的标题应是一条符合 Conventional Commits 的 message正文可汇总 PR 描述。6. 分支与 Commit 类型对照分支前缀推荐 Commit 类型典型合入目标feature/*featdevelop/mainfix/*、bugfix/*fixdevelophotfix/*fixmaindeveloprelease/*chore版本 bumpmaindeveloprefactor/*refactordevelopchore/*chore、build、cidevelopdocs/*docsdevelop7. 分支生命周期创建 ──► 开发与目标分支同步──► PR 评审 ──► CI 通过 ──► 合入 ──► 删除远程分支阶段要求创建从最新的目标长期分支拉取命名符合 §3开发定期rebase或merge目标分支减少冲突小步提交、语义清晰评审PR 标题遵循 Conventional Commits关联 Issue描述影响范围与测试方式合入CI 绿 至少 1 人 Approve团队可规定 2 人清理合入后 2448h 内删除远程短期分支分支存活期建议分支类型建议最长存活feature/*≤ 2 周fix/*≤ 3 天hotfix/*≤ 24 小时release/*至发布完成experiment/*≤ 1 周过期即删8. 快速对照表场景从哪拉合入哪分支名示例新功能Git Flowdevelopdevelopfeature/oauth2-login新功能GitHub Flowmainmainfeature/oauth2-login开发期 Bugdevelopdevelopfix/session-expiry生产热修mainmaindevelophotfix/payment-timeout版本发布developmain Tagrelease/1.4.0依赖升级developdevelopchore/upgrade-deps技术验证develop不合 main转 featureexperiment/graphql-poc9. 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 messagehuskyGit hooks 触发 lint/testsemantic-release按 commit 自动 bump 版本、发 Tag、生成 CHANGELOGrelease-pleaseGoogle 风格自动化发布Branch protection rules强制 PR、CI、Reviewpre-commit 示例commitlint{ extends: [commitlint/config-conventional] }11. 修订记录版本日期说明2.02026-07-10重写为业界通用规范Conventional Commits、SemVer、Git Flow/GitHub Flow去除项目特定命名1.0—项目定制版已 supersede附录 AConventional Commits 完整类型速查feat → 新功能 fix → Bug 修复 docs → 文档 style → 代码格式不影响含义 refactor → 重构 perf → 性能 test → 测试 build → 构建/依赖 ci → 持续集成 chore → 杂项维护 revert → 回滚附录 BSemVer 升级规则摘要变更性质版本段示例破坏性 API/行为变更MAJOR1.4.0 →2.0.0向后兼容的新功能MINOR1.4.0 → 1.5.0向后兼容的 Bug 修复PATCH1.4.0 → 1.4.1附录 C参考链接Conventional CommitsSemantic Versioning 2.0.0A successful Git branching model (Git Flow)GitHub FlowTrunk Based DevelopmentAngular Commit Message Guidelines