106 lines
5.7 KiB
Markdown
106 lines
5.7 KiB
Markdown
# **5.1 版本控制与代码提交规范**
|
||
|
||
优秀的版本控制应当像一本条理清晰的编年史，任何人在任何时候接手代码，都能通过 Git 历史精准还原业务的演进过程。本规范旨在建立清晰、可追溯、自动化的代码流转体系。
|
||
|
||
### **5.1.1 分支管理模型 (Branching Model)**
|
||
|
||
为了兼顾敏捷交付与生产环境的极度稳定，团队统一采用 **简化的 GitFlow / 环境变量流 (Environment Flow)**。
|
||
|
||
#### **1\. 核心常驻分支 (Protected Branches)**
|
||
|
||
这三个核心分支与部署环境严格绑定，**绝对禁止**任何开发人员直接使用 git push 推送代码，必须通过 PR/MR 流程合并：
|
||
|
||
* **main (或 master) \- 生产环境分支**：
|
||
* 对应线上生产环境 (Production)。
|
||
* 这里的代码必须是随时可发布、经过全面测试的绝对稳定版本。
|
||
* **test (或 release) \- 测试/预发环境分支**：
|
||
* 对应 QA 测试环境或预发布环境 (Staging)。
|
||
* 用于产品经理验收和测试工程师进行系统级回归测试。
|
||
* **dev (或 develop) \- 开发集成环境分支**：
|
||
* 对应日常开发联调环境。
|
||
* 汇总所有开发人员最新的 Feature 代码，允许存在一定的 Break Change，但必须保证编译和基础启动不报错。
|
||
|
||
#### **2\. 临时工作分支 (Temporary Branches)**
|
||
|
||
开发人员日常编码都在临时分支上进行，命名必须遵循以下前缀规范，并在开发完成后删除：
|
||
|
||
* **feat/xxx**：新功能开发分支（从 dev 检出，合并回 dev）。
|
||
* *示例：feat/user-login-wechat*
|
||
* **fix/xxx**：常规 Bug 修复分支（从 dev 或 test 检出）。
|
||
* *示例：fix/order-amount-calc-error*
|
||
* **hotfix/xxx**：线上紧急漏洞修复分支（**直接从 main 检出**）。
|
||
* *红线：紧急修复测试通过后，必须同时双向合并到 main 和 dev 分支，防止代码覆盖丢失！*
|
||
|
||
### **5.1.2 Commit Message 格式规范 (Conventional Commits)**
|
||
|
||
**核心理念：让机器能读懂提交历史，以便自动生成 Release Notes。**
|
||
|
||
团队强制遵循 Angular 提交规范。推荐在项目中引入 commitlint 配合 Git Hooks（如 pre-commit）进行强制拦截。
|
||
|
||
#### **1\. 标准格式**
|
||
|
||
\<type\>(\<scope\>): \<subject\>
|
||
\<空行\>
|
||
\<body\>
|
||
|
||
#### **2\. Type (提交类型 \- 必填)**
|
||
|
||
* feat: ✨ 新增功能 (Feature)
|
||
* fix: 🐛 修复缺陷 (Bug)
|
||
* docs: 📝 文档更新 (Documentation)
|
||
* style: 🎨 代码格式修改（不影响逻辑，如空格、缩进、格式化工具输出）
|
||
* refactor: ♻️ 代码重构（既不是新增功能，也不是修复 bug 的代码更改）
|
||
* perf: ⚡️ 性能优化 (Performance)
|
||
* test: ✅ 新增或修改测试用例
|
||
* chore: 🔧 构建过程、CI/CD 脚本、辅助工具库的更改
|
||
|
||
#### **3\. Scope (影响范围 \- 可选)**
|
||
|
||
用于说明本次提交影响的模块，如 (user), (order-service), (ci)。
|
||
|
||
#### **4\. Subject (简短描述 \- 必填)**
|
||
|
||
* 必须使用祈使句（如：“添加用户登录”，而不是“添加了用户登录”）。
|
||
* 结尾**不要**加句号。
|
||
* 如果关联了特定的任务卡片或 Issue 编号，强烈建议带上（如：feat(auth): 支持微信扫码登录 (\#ISSUE-102)）。
|
||
|
||
#### **4\. 反面教材与正确示范**
|
||
|
||
* ❌ 错误：update 代码
|
||
* ❌ 错误：fix bug
|
||
* ✅ 正确：fix(payment): 修复并发退款时状态一致性问题 (\#bug-882)
|
||
* ✅ 正确：feat(externals): 增加 Dify 代理网关接口
|
||
|
||
### **5.1.3 Tag 与版本号命名规则 (Semantic Versioning)**
|
||
|
||
**红线：严禁人肉编造随意字符串作为版本号。** 所有对外发布、打包上线的制品（如 Docker 镜像、NPM 包、Maven 依赖）必须严格遵循 **语义化版本 (SemVer 2.0.0)** 规范。
|
||
|
||
#### **1\. 版本号格式：v\<MAJOR\>.\<MINOR\>.\<PATCH\>**
|
||
|
||
* **MAJOR (主版本号)**：当你做了**不兼容的 API 修改**或系统进行了史诗级重构时。
|
||
* **MINOR (次版本号)**：当你做了**向下兼容的新功能新增**时。
|
||
* **PATCH (修订号)**：当你做了**向下兼容的缺陷修复 (Bugfix)** 时。
|
||
|
||
*示例：v1.0.0 \-\> v1.1.0 (加了新功能) \-\> v1.1.1 (修了新功能的 Bug) \-\> v2.0.0 (接口大重构，老版本客户端不可用)。*
|
||
|
||
#### **2\. 预发布版本后缀**
|
||
|
||
在正式 Tag 之前，如果是处于测试阶段的里程碑，应当追加连字符与标识：
|
||
|
||
* Alpha (内测版): v2.0.0-alpha.1
|
||
* Beta (公测版): v2.0.0-beta.1
|
||
* RC (Release Candidate 候选发布版): v2.0.0-rc.1
|
||
|
||
### **5.1.4 提交与合并纪律 (Commit & Merge Discipline)**
|
||
|
||
为配合 4.2 代码审查规范 与 CI/CD 质量门禁，特设立以下代码流转纪律：
|
||
|
||
1. **防门禁失败兜底 (Pre-commit)**：
|
||
* 所有代码在 git commit 时，必须触发本地钩子验证。如项目存在特定的门禁脚本（如 GTCO\_AI 项目下的 scripts/ci/quality\_gate.sh），必须在本地保证执行通过。
|
||
2. **禁止强推 (No Force Push)**：
|
||
* 绝对禁止对 dev, test, main 等公共分支执行 git push \-f。此行为将直接导致团队其他成员的版本库断裂。
|
||
3. **主张 Squash Merge (压缩合并)**：
|
||
* 开发者在自己的 feat/xxx 分支上为了备份，可能会产生大量零碎的 commit（如 fix typo, update again）。
|
||
* 在通过 PR 合并到主干分支（如 dev）时，**强烈建议使用 Squash and Merge**，将无数琐碎的 commit 压缩成一个整洁的业务 Commit 记录进入主干。
|
||
4. **及时变基 (Rebase / Sync)**：
|
||
* 开发周期较长的 Feature 分支，必须每天从目标主干分支拉取最新代码（建议使用 git pull \--rebase origin dev），提前解决冲突，严禁等到提 PR 那天才去处理几千行的灾难性冲突。 |