Git 使用规范
一、版本控制的核心原则 🧭
主分支（
main / master）仅用于发布稳定版本，不用于日常开发。主分支始终保持可部署状态，确保版本稳定、可追溯。
所有功能开发必须在独立分支上完成。
每项功能、修复或改动应创建独立分支，避免协作冲突，提升开发效率与可维护性。
每次提交都应具备明确目的与描述。
保持提交记录清晰、结构化，便于代码审查、问题回溯和历史审计。
每次正式发布必须打 Tag，并提供详细的变更说明（Changelog）。
Tag 应遵循语义化版本控制（如
v1.2.3），变更说明需涵盖新增、优化、修复等内容。严禁直接向主分支推送代码，所有更改必须通过合并请求（Pull Request / Merge Request）提交。
所有合并操作需经由代码审核流程，确保团队协作质量与一致性。
二、分支策略（Branch Strategy） 🌿
2.1 分支类型与命名规范
| 分支类型 | 命名规则 | 示例 | 说明 |
|---|---|---|---|
| 主分支 | main 或 master |
master |
生产部署分支，仅用于发布版本和打 Tag，不参与开发 |
| 开发分支 | develop |
develop |
日常开发集成分支，所有功能分支合并归此，保持阶段性稳定 |
| 功能分支 | feature/<模块>-<功能>-<任务ID> |
feature/user-login-1234 |
单个功能开发分支，从 develop 创建，开发完成后合并回 develop |
| 修复分支 | bugfix/<模块>-<简要描述> |
bugfix/userlist-null-pointer |
非紧急的缺陷修复，从 develop 创建，修复后合并回 develop |
| 热修复分支 | hotfix/<简要描述> |
hotfix/fix-prod-login |
生产环境紧急修复，从 master 创建，修复后合并回 master 和 develop |
| 发布准备分支 | release/v<版本号> |
release/v2.0.0 |
发布前版本封版处理，如补充文档、调整配置等，从 develop 创建，合并回 master 和 develop |
| 测试分支 | test |
test |
用于部署测试环境，合并开发分支后测试用 |
| 灰度分支 | gray |
gray |
用于灰度部署或内部试运行，通常从 release 或 master 派生 |
2.2 可视化流程图
feature/* ─┬─→ develop ─┬─→ test ─┬─→ release ─┬─→ gray ─→ master
│ │ │ │
└────────────┘ └── hotfix ───┘
三、提交信息规范（Commit Message）✍️
3.1 提交格式
<type>: <subject>
// 示例
feat: 添加用户登录接口
fix: 修复订单状态不更新的问题
3.2 Type 类型说明
| 类型 | 说明 |
|---|---|
| feat | 新增功能（Feature） |
| fix | 修复 Bug（Bug Fix） |
| docs | 文档变更（例如 README、说明文档） |
| style | 代码格式调整（空格、缩进、逗号等，不影响功能） |
| refactor | 代码重构（既不新增功能也不修复 Bug） |
| perf | 性能优化 |
| test | 添加或修改测试代码 |
| chore | 杂项更新（构建脚本、依赖管理、工具配置等） |
| revert | 回滚，撤销之前的提交 |
| build | 与构建系统或外部依赖相关的更改 |
| ci | 持续集成/持续部署（CI/CD）配置文件修改 |
四、Tag 版本规范（Tag Strategy）🔖
4.1 命名格式
Tag 命名遵循语义化版本控制规范（Semantic Versioning，SemVer），格式如下：
v<主版本号>.<次版本号>.<补丁号>[-预发布标签]
| 版本类型 | 示例 | 说明 |
|---|---|---|
| 正式版本 | v1.2.0 |
用于生产环境的正式发布版本 |
| Beta 版本 | v1.2.0-beta.1 |
第一个 Beta 测试版本 |
| RC 版本 | v1.2.0-rc.1 |
候选发布版本（Release Candidate） |
4.2 Tag 描述说明建议
打 Tag 时，建议使用带注释的 Tag，并附带简洁明确的版本说明，示例如下：
git tag -a v2.0.0 -m "Release v2.0.0: 添加国际化、多语言支持"
-a表示创建带注释的 Tag-m后面跟随的是该版本的说明信息，建议包含主要变更点，方便回溯与沟通
五、推荐工作流（基于 Git Flow 简化 + 自动化）🔄
5.1 分支来源与合并目标
| 开发阶段 | 分支来源 | 合并目标 | 说明 |
|---|---|---|---|
| 功能开发 | develop |
develop |
日常功能开发，持续集成 |
| Bug 修复 | develop |
develop |
非紧急缺陷修复 |
| 热修复 | master |
master + develop |
紧急修复生产环境问题，双向合并 |
| 发布准备 | develop |
release |
发布前版本冻结与准备 |
| 灰度发布 | release |
gray |
灰度环境部署与验证 |
| 正式发布 | gray |
master |
通过灰度验证后正式发布 |
5.2 PR / MR 流程规范
所有代码合并必须通过 Pull Request（PR）或 Merge Request（MR）完成。
合并前需至少一名开发人员审核通过。
合并提交信息应简洁明了，保证提交历史整洁。
六、CI/CD 与自动化建议（基于 Jenkins）📦
6.1 自动部署策略（推荐）
| 分支 | 部署环境 | 说明 |
|---|---|---|
develop |
开发环境 | 持续集成开发版本自动部署 |
test |
测试环境 | 功能验证与集成测试环境 |
gray |
灰度环境 | 内部灰度发布与预发布验证 |
master（打 Tag） |
正式环境 | 正式生产环境部署，仅限打 Tag 时触发 |
6.2 推荐工具集与 Jenkins 集成建议
| 功能 | 工具示例 | Jenkins 集成建议 |
|---|---|---|
| 提交校验 | Husky + Commitlint | 在 Jenkins 构建前通过钩子脚本验证提交规范 |
| 自动构建部署 | Jenkins Pipeline | 采用 Declarative Pipeline 编写自动化流水线，实现构建、测试、部署 |
| 代码静态检查 | ESLint / Prettier | 集成静态代码扫描插件（如 Warnings Next Generation）并生成报告 |
| 发布日志生成 | standard-version / semantic-release | 结合 Jenkins 任务自动生成版本日志，并触发自动发布 |
6.3 Jenkins 流程示例
触发机制：
监听代码仓库分支推送事件（webhook）
Tag 创建触发正式发布流程
手动触发构建
流水线步骤：
代码拉取 → 提交信息校验 → 代码静态检查 → 单元测试 → 构建 → 部署 → 发布通知
分支策略支持：
develop、test、gray、master分支分别配置对应流水线任务或参数化构建
七、常见问题处理建议 📌
| 问题 | 说明 | 建议 |
|---|---|---|
| 忘记切分支开发 | 直接在 develop 写代码 |
严格要求功能必须基于 feature/* 分支 |
| 提交信息混乱 | update code、fix 等 |
启用 Commitlint 校验，模板统一 |
| 主分支误操作 | 直接 push 到 master |
设置分支保护（Require PR、禁用 force push） |
| 多人合并冲突频繁 | 提交粒度大 | 频繁同步、提前拉 develop，保持分支短生命周期 |