|
|
@@ -238,6 +238,182 @@ flowchart TD
|
|
|
|
|
|
**示例参考**：`dw_base/io/README.md`、`dw_base/pm/README.md`、`dw_base/dq/README.md`、`dw_base/sync/README.md`、`dw_base/ops/README.md`、`tests/README.md`。
|
|
|
|
|
|
+### 4.6 Git 协作规范
|
|
|
+
|
|
|
+本节定义数仓项目团队使用 Git 协作的分支模型与工作流程，保证主干历史整洁可追溯，降低多人协作冲突风险。
|
|
|
+
|
|
|
+#### 4.6.1 分支模型
|
|
|
+
|
|
|
+##### 4.6.1.1 分支总览
|
|
|
+
|
|
|
+| 分支 | 定位 | 受保护 | 合并来源 | 触发动作 |
|
|
|
+|------|------|--------|----------|----------|
|
|
|
+| `master` | 稳定版本归档 | 是 | `release` | 打 Tag（里程碑、冒烟通过等） |
|
|
|
+| `release` | 线上运行版本 | 是 | `feature` | 发布到线上 |
|
|
|
+| `feature` | 公共开发分支 | 是 | `feature-xxx`(个人分支) | 测试通过后合入 `release` |
|
|
|
+| `feature-xxx` | 个人开发分支 | 否 | —— | 通过 PR 合入 `feature` 后自动删除 |
|
|
|
+
|
|
|
+##### 4.6.1.2 分支结构
|
|
|
+
|
|
|
+```
|
|
|
+ [tag: datax+spark-smoke-2026-04-20]
|
|
|
+ │
|
|
|
+ master ──────────────────────────●─────────────────────▶ (稳定版本归档)
|
|
|
+ ↗
|
|
|
+ ↗ merge (里程碑 / 冒烟通过)
|
|
|
+ ↗
|
|
|
+ release ────●────●────●──────●──────────────────────────▶ (线上版本)
|
|
|
+ ↑ ↑ ↑
|
|
|
+ │ │ │ merge (测试通过后发布)
|
|
|
+ │ │ │
|
|
|
+ feature ─●──●─●──●─●──●──────────────────────────────────▶ (公共开发)
|
|
|
+ ↑ ↑ ↑
|
|
|
+ │ │ │ PR + Review (管理员合并)
|
|
|
+ │ │ │
|
|
|
+ │ │ └── feature-lisi-dwd-trd-20260418 ✗ (PR 合入后自动删除)
|
|
|
+ │ └────── feature-wangwu-dim-shp-20260419 ✗ (PR 合入后自动删除)
|
|
|
+ └─────────── feature-zhangsan-ods-usr-20260420 ✗ (PR 合入后自动删除)
|
|
|
+```
|
|
|
+
|
|
|
+##### 4.6.1.3 保护策略
|
|
|
+
|
|
|
+`master`、`release`、`feature` 三个分支在仓库层面禁用远程推送，所有变更必须通过 PR（Pull Request / Merge Request）流转，仅允许管理员通过合并操作更新。
|
|
|
+
|
|
|
+#### 4.6.2 代码流转路径
|
|
|
+
|
|
|
+```mermaid
|
|
|
+flowchart LR
|
|
|
+ A[feature-xxx<br/>个人分支] -->|PR + Review| B[feature<br/>公共开发]
|
|
|
+ B -->|测试通过<br/>线上发布| C[release<br/>线上版本]
|
|
|
+ C -->|里程碑/冒烟通过<br/>打 Tag| D[master<br/>稳定归档]
|
|
|
+```
|
|
|
+
|
|
|
+代码单向汇聚到 `master`，各合并节点由管理员操作，`release` → `master` 的合并提交需打 Tag。
|
|
|
+
|
|
|
+#### 4.6.3 开发者工作流
|
|
|
+
|
|
|
+```mermaid
|
|
|
+sequenceDiagram
|
|
|
+ participant Dev as 开发者
|
|
|
+ participant Local as 本地仓库
|
|
|
+ participant Remote as 远端仓库
|
|
|
+ participant Admin as 管理员
|
|
|
+
|
|
|
+ Dev->>Remote: fetch origin
|
|
|
+ Dev->>Local: 基于最新 origin/feature 新建个人分支
|
|
|
+ Note over Dev,Local: 每次新任务必须重新拉取 feature 建分支
|
|
|
+
|
|
|
+ loop 日常开发
|
|
|
+ Dev->>Local: 编码 + commit
|
|
|
+ end
|
|
|
+
|
|
|
+ Note over Dev,Remote: 提 PR 前必须同步远端 feature
|
|
|
+ Dev->>Remote: fetch origin feature
|
|
|
+ Dev->>Local: rebase origin/feature
|
|
|
+
|
|
|
+ alt 有冲突
|
|
|
+ Dev->>Local: 本地解决冲突后继续 rebase
|
|
|
+ end
|
|
|
+
|
|
|
+ Dev->>Remote: push --force-with-lease 推送个人分支
|
|
|
+ Dev->>Remote: 网页端发起 PR
|
|
|
+
|
|
|
+ Admin->>Remote: Code Review
|
|
|
+ alt Review 通过
|
|
|
+ Admin->>Remote: 合并 PR 到 feature
|
|
|
+ Remote-->>Remote: 自动删除 feature-xxx
|
|
|
+ else 需要修改
|
|
|
+ Admin-->>Dev: 提出修改意见
|
|
|
+ Dev->>Local: 修改后重复 rebase + 强推
|
|
|
+ end
|
|
|
+```
|
|
|
+
|
|
|
+**关键约束**：
|
|
|
+
|
|
|
+- **新建分支与提 PR 前必须先 `fetch` 远端**，以 `origin/feature` 的最新状态为基准，禁止以本地 `feature` 为基准（本地 `feature` 可能滞后于远端）
|
|
|
+- **个人分支必须基于最新 `origin/feature` 创建**，禁止复用已合并 PR 的旧个人分支
|
|
|
+- **提 PR 前必须 rebase `origin/feature`**，冲突在本地解决后继续 rebase
|
|
|
+- **强推一律使用 `--force-with-lease`**，禁用 `--force`
|
|
|
+- **PR 合并后远端个人分支自动删除**，下次任务重新 fetch 后基于 `origin/feature` 建新分支
|
|
|
+
|
|
|
+日常通过 PyCharm 的 Git 面板与仓库网页端完成上述操作即可。
|
|
|
+
|
|
|
+#### 4.6.4 要求使用 Rebase 而非 Merge
|
|
|
+
|
|
|
+- **历史线性整洁**：没有冗余的 merge 提交，可视化合并树清晰
|
|
|
+- **二分查找友好**：`git bisect` 定位问题提交更精准
|
|
|
+- **Review 聚焦**：PR 里只有本次任务的提交，Reviewer 不会看到与本次无关的 merge commit
|
|
|
+
|
|
|
+#### 4.6.5 Hotfix 紧急修复流程
|
|
|
+
|
|
|
+线上 `release` 分支出现紧急故障时，走独立的 hotfix 流程，避免等待 `feature` 中未完成功能的流转。
|
|
|
+
|
|
|
+##### 4.6.5.1 流转路径
|
|
|
+
|
|
|
+```mermaid
|
|
|
+flowchart LR
|
|
|
+ A[release<br/>线上版本] -->|基于 release 拉出| B[hotfix-xxx<br/>修复分支]
|
|
|
+ B -->|PR #1 + Review| A
|
|
|
+ B -->|PR #2 + Review| D[feature<br/>公共开发]
|
|
|
+ A -->|修复验证通过<br/>打 hotfix tag| C[master<br/>稳定归档]
|
|
|
+```
|
|
|
+
|
|
|
+**关键点**：同一个 `hotfix-xxx` 分支需要发起**两个 PR**，分别合入 `release` 和 `feature`，保证后续开发基于已修复的代码。两个 PR 都合并后再删除 hotfix 分支。
|
|
|
+
|
|
|
+> 为什么不是 `release` 合入 `feature`？`release` 本身由大量 merge commit 构成，反向合入会污染 `feature` 的线性历史。用 hotfix 分支发两个 PR，两边拿到的都是同一个独立的修复提交。
|
|
|
+
|
|
|
+##### 4.6.5.2 操作步骤
|
|
|
+
|
|
|
+1. 开发者基于最新 `origin/release` 创建 `hotfix-xxx` 分支，**只做 bug 修复，不夹带其他改动**
|
|
|
+2. 提 PR #1 至 `release`，管理员 Review 通过后合入，**暂不删除 hotfix 分支**
|
|
|
+3. 管理员 / QA 验证修复并部署线上
|
|
|
+4. 开发者基于同一 hotfix 分支提 PR #2 至 `feature`
|
|
|
+5. 管理员 Review 通过后合入 `feature`，删除 hotfix 分支
|
|
|
+6. 管理员将 `release` 合入 `master` 并打 hotfix tag
|
|
|
+
|
|
|
+##### 4.6.5.3 冲突异常处理
|
|
|
+
|
|
|
+正常情况下 PR #2 不应产生冲突——hotfix 职责单一，`feature` 上不应存在针对同一代码的并行修改。
|
|
|
+
|
|
|
+**若产生冲突，说明 `feature` 上有人改动了 hotfix 修复的同一区域**。此时**不要自行解决冲突**，否则会出现 `release` 与 `feature` 修复版本不一致，后续发布可能导致 bug 复现。正确做法：暂停合并，由管理员召集 hotfix 作者与 `feature` 侧的改动者协调，确认最终版本后再继续。
|
|
|
+
|
|
|
+#### 4.6.6 分支 / Tag 命名
|
|
|
+
|
|
|
+##### 4.6.6.1 个人分支命名
|
|
|
+
|
|
|
+格式：`feature-<姓名拼音>-<描述>-<日期>`
|
|
|
+
|
|
|
+| 示例 | 含义 |
|
|
|
+|------|------|
|
|
|
+| `feature-lisi-dwd-trd-20260418` | 李四开发交易域 DWD 层，2026-04-18 建分支 |
|
|
|
+| `feature-wangwu-dim-shp-20260419` | 王五开发商品维度，2026-04-19 建分支 |
|
|
|
+| `feature-zhangsan-ods-usr-20260420` | 张三开发用户域 ODS 层，2026-04-20 建分支 |
|
|
|
+
|
|
|
+##### 4.6.6.2 Hotfix 分支命名
|
|
|
+
|
|
|
+格式：`hotfix-<姓名拼音>-<故障简述>-<日期>`
|
|
|
+
|
|
|
+| 示例 | 含义 |
|
|
|
+|------|------|
|
|
|
+| `hotfix-zhangsan-ods-usr-duplicate-20260421` | 修复用户域 ODS 层数据重复 |
|
|
|
+| `hotfix-lisi-ads-prd-null-20260422` | 修复产品宽表空值异常 |
|
|
|
+| `hotfix-wangwu-dws-mkt-stale-20260423` | 修复营销宽表数据滞后 |
|
|
|
+
|
|
|
+##### 4.6.6.3 Tag 命名
|
|
|
+
|
|
|
+格式：`<描述>-<类型>-<日期>`
|
|
|
+
|
|
|
+| 示例 | 含义 |
|
|
|
+|------|------|
|
|
|
+| `datax+spark-smoke-2026-04-20` | DataX + Spark 链路冒烟测试通过 |
|
|
|
+| `dim-calendar-smoke-2026-04-18` | dim_calendar 维度表冒烟通过 |
|
|
|
+| `ods-usr-duplicate-hotfix-2026-04-21` | ODS 用户域数据重复修复上线 |
|
|
|
+
|
|
|
+**规则**：
|
|
|
+
|
|
|
+- 阶段类型：`smoke`（冒烟通过）、`hotfix`（紧急修复）
|
|
|
+- Tag 打在 `release` → `master` 的合并提交上，由管理员操作
|
|
|
+
|
|
|
## 5. 测试规范
|
|
|
|
|
|
见 `90-重构路线.md` §6。核心要点：
|
