yinjianm
136 lines
5.9 KiB
Markdown
136 lines
5.9 KiB
Markdown
# 变更提案: merge-upstream-preserve-local
|
|
|
|
## 元信息
|
|
```yaml
|
|
类型: 优化
|
|
方案类型: implementation
|
|
优先级: P1
|
|
状态: 已确认
|
|
创建: 2026-04-16
|
|
```
|
|
|
|
---
|
|
|
|
## 1. 需求
|
|
|
|
### 背景
|
|
当前工作分支位于 `master`，本地相对 `upstream/master` 领先 15 个提交、落后 47 个提交。
|
|
用户要求在保留所有本地改动与本地功能优先级的前提下，将 `https://github.com/cedar2025/Xboard`
|
|
的最新代码合并到当前分支。现场还存在未跟踪的 `.helloagents/` 目录，以及
|
|
`public/assets/admin` 子模块指针与 `upstream/master` 不一致，需要在合并时避免误覆盖。
|
|
|
|
### 目标
|
|
- 将 `upstream/master` 的最新提交合并到当前分支。
|
|
- 保留当前分支已有提交与本地工作树内容，不做重置、不强推、不丢改动。
|
|
- 当出现文本冲突时优先保留当前分支的实现。
|
|
- 当出现子模块指针冲突时，显式保留当前分支所指向的子模块版本，并完成核对。
|
|
|
|
### 约束条件
|
|
```yaml
|
|
时间约束: 当前回合内完成保护、合并、冲突处理和结果核验
|
|
性能约束: N/A
|
|
兼容性约束: 不改变当前分支名称，不破坏已有 Git 历史，避免影响未跟踪的本地目录
|
|
业务约束: 发生冲突时以用户本地功能优先；不使用 reset --hard 或覆盖式同步
|
|
```
|
|
|
|
### 验收标准
|
|
- [ ] 已成功抓取并合并 `upstream/master` 到当前分支，且本地 15 个领先提交仍保留在历史中
|
|
- [ ] 工作树中的本地未跟踪内容未丢失，合并冲突已处理完毕
|
|
- [ ] 若产生冲突，文本文件优先保留当前分支实现；`public/assets/admin` 子模块指针按当前分支版本保留并确认
|
|
- [ ] 合并后完成基本核验，包括分叉变化、工作树状态、子模块状态与冲突标记清零
|
|
|
|
---
|
|
|
|
## 2. 方案
|
|
|
|
### 技术方案
|
|
采用“保护现场 + 常规 merge + 冲突偏向当前分支 + 显式核对子模块”的方案：
|
|
|
|
1. 记录当前现场，包括分支、工作树、与 `upstream/master` 的分叉和子模块指针。
|
|
2. 创建本地安全锚点（备份分支或标签），确保任何一步异常都可回到操作前状态。
|
|
3. 视需要暂存未跟踪内容，避免合并期间被意外干扰。
|
|
4. 执行 `git merge -X ours upstream/master`，让文本冲突默认偏向当前分支。
|
|
5. 如出现子模块指针冲突，手工恢复为当前分支所引用的子模块提交，而不是盲目接受上游版本。
|
|
6. 完成后检查 `git status`、分叉计数、merge commit、子模块状态和冲突残留，确认结果满足“本地优先”要求。
|
|
|
|
### 影响范围
|
|
```yaml
|
|
涉及模块:
|
|
- Git 历史: 当前分支将新增一次来自 upstream/master 的合并结果
|
|
- 根仓工作树: 可能因上游更新而变更多个跟踪文件
|
|
- public/assets/admin: 子模块指针可能出现冲突，需要显式保留本地版本
|
|
- .helloagents/plan: 新增本次操作的方案包与执行记录
|
|
预计变更文件: 多文件，数量取决于 upstream/master 与当前分支差异
|
|
```
|
|
|
|
### 风险评估
|
|
| 风险 | 等级 | 应对 |
|
|
|------|------|------|
|
|
| `-X ours` 仅对文本冲突生效，无法自动正确处理子模块指针 | 高 | 合并后单独检查 `public/assets/admin`，必要时显式 checkout 当前分支的子模块提交 |
|
|
| 未跟踪的 `.helloagents/` 内容在操作中被误干扰 | 中 | 先记录现场，必要时仅暂存未跟踪内容，不删除任何本地文件 |
|
|
| 上游 47 个提交引入的结构变化与本地 15 个提交存在深度冲突 | 中 | 保留备份锚点，逐项处理冲突并在结果核验中确认本地功能仍存在 |
|
|
| 误把 `origin/master` 当作基线导致合并方向错误 | 低 | 固定以 `upstream/master` 为唯一上游基线执行本次合并 |
|
|
|
|
---
|
|
|
|
## 3. 技术设计（可选）
|
|
|
|
> 本次为 Git 合并操作，无架构/API/数据模型设计变更。
|
|
|
|
### 架构设计
|
|
N/A
|
|
|
|
### API设计
|
|
N/A
|
|
|
|
### 数据模型
|
|
N/A
|
|
|
|
---
|
|
|
|
## 4. 核心场景
|
|
|
|
> 本次为仓库合并操作，不涉及业务模块文档同步场景。
|
|
|
|
### 场景: 当前分支合并 upstream/master
|
|
**模块**: Git 仓库 / 子模块
|
|
**条件**: 当前分支存在本地领先提交，且用户要求本地实现优先
|
|
**行为**: 拉取 upstream 最新提交并合并到当前分支，冲突时优先保留当前分支内容，子模块指针冲突显式保留当前指针
|
|
**结果**: 当前分支吸收上游更新，同时保住本地提交和本地优先实现
|
|
|
|
---
|
|
|
|
## 5. 技术决策
|
|
|
|
> 本方案涉及的技术决策，归档后成为决策的唯一完整记录
|
|
|
|
### merge-upstream-preserve-local#D001: 采用 merge 而非 reset、rebase 或手工摘取提交
|
|
**日期**: 2026-04-16
|
|
**状态**: ✅采纳
|
|
**背景**: 用户要求“保留所有本地更改”并把远端最新代码合并到当前项目，同时冲突时本地功能优先。需要选择一种既能保留历史又便于冲突处理的更新方式。
|
|
**选项分析**:
|
|
| 选项 | 优点 | 缺点 |
|
|
|------|------|------|
|
|
| A: `git merge -X ours upstream/master` | 保留分支历史，适合把上游更新并入当前分支，文本冲突可偏向本地实现 | 不能自动正确处理子模块指针，需要额外检查 |
|
|
| B: `git rebase upstream/master` | 历史更线性 | 会重写当前分支提交，冲突重放次数可能更多，不符合“尽量保留现状” |
|
|
| C: `git reset --hard upstream/master` 后再回放本地改动 | 操作简单 | 高风险，会直接破坏当前现场，不符合需求 |
|
|
**决策**: 选择方案 A
|
|
**理由**: 常规 merge 最符合“保留本地提交和现场”的要求，结合 `-X ours` 能让文本冲突尽量偏向当前分支；剩余的子模块冲突可控且可显式核验。
|
|
**影响**: 影响当前分支历史、根仓工作树状态，以及 `public/assets/admin` 子模块指针处理方式
|
|
|
|
---
|
|
|
|
## 6. 成果设计
|
|
|
|
> 含视觉产出的任务由 DESIGN Phase2 填充。非视觉任务整节标注"N/A"。
|
|
|
|
### 设计方向
|
|
- N/A
|
|
|
|
### 视觉要素
|
|
- N/A
|
|
|
|
### 技术约束
|
|
- **可访问性**: N/A
|
|
- **响应式**: N/A
|