74 lines
3.1 KiB
Markdown
74 lines
3.1 KiB
Markdown
# 上游代码同步架构指南 (Upstream Synchronization Guide)
|
||
|
||
## 1. 核心理念 (Core Philosophy)
|
||
|
||
作为基于开源项目二次开发的商业项目，我们采用 **"双流分支策略" (Dual-Stream Branching Strategy)**。这一策略旨在解决以下核心冲突：
|
||
* **Keep Updated**: 必须紧跟官方 bug 修复和新特性。
|
||
* **Keep Customized**: 必须严格保留私有的 UI 定制和资源修改。
|
||
|
||
## 2. 分支架构 (Branch Architecture)
|
||
|
||
我们维护两个长期的核心分支：
|
||
|
||
### A. `upstream-main` (官方纯净流)
|
||
* **定义**: 官方代码在本地的**只读镜像**。
|
||
* **规则**:
|
||
1. **严禁**直接修改此分支代码。
|
||
2. 仅通过 `git pull upstream main` 更新。
|
||
* **作用**: 作为 Merge 的基准（Base），确保我们清楚知道“官方改了什么”。
|
||
|
||
### B. `master` (私有定制流)
|
||
* **定义**: 我们的生产环境主分支。
|
||
* **组成**: `upstream-main` + `私有补丁 (Custom Patches)`。
|
||
* **私有补丁内容**:
|
||
* `images/` 下的定制资源。
|
||
* `UI Widgets` 的样式调整（如 `video_screen.dart` 的改动）。
|
||
|
||
### C. `LOCAL_CHANGES.md` (变更白皮书)
|
||
* **定义**: 项目的“差异账本”。
|
||
* **规则**: 任何不跟随官方的修改，**必须**在此文件记录。这能让我们在合并冲突时快速回忆起“这是我们故意改的”还是“意外”。
|
||
|
||
## 3. 同步工作流 (Synchronization Workflow)
|
||
|
||
|
||
每当需要同步官方更新时，执行以下标准流程（Standard Operating Procedure）：
|
||
|
||
1. **更新基准**: 切换到 `upstream-main` 并拉取最新官方代码。
|
||
2. **执行合并**: 切换回 `master`，合并 `upstream-main`。
|
||
3. **资源保护**: 如果发生冲突，始终以 `master` 的 `images/` 为准（"Ours" 策略）。
|
||
|
||
## 4. 自动化脚本 (Automation)
|
||
|
||
为了降低人为失误，我们提供了自动化脚本 `scripts/sync_from_upstream.sh`。
|
||
|
||
### 脚本逻辑
|
||
1. 自动 Fetch `upstream`。
|
||
2. 重置 `upstream-main` 到最新官方 commit。
|
||
3. 尝试合并到 `master`。
|
||
4. **关键保护**:哪怕没有冲突，脚本也会强制检查并恢复 `images/` 目录到合并前的状态，确保私有资源不被官方资源覆盖。
|
||
|
||
```bash
|
||
# 执行方式
|
||
./scripts/sync_from_upstream.sh
|
||
```
|
||
|
||
---
|
||
**Architect Note**: 保持 `upstream-main` 的纯净是此架构的基石。一旦该分支被污染，差异对比将失去意义。
|
||
|
||
## 5. 如何在其他项目复用 (How to Reuse)
|
||
|
||
如果您有其他类似项目（既要跟上游，又有本地定制），请按以下步骤复用此方案：
|
||
|
||
1. **复制脚本**: 将 `scripts/sync_from_upstream.sh` 复制到新项目的 `scripts/` 目录。
|
||
2. **配置参数**: 打开复制后的脚本，编辑顶部的配置项：
|
||
```bash
|
||
# 配置您的上游仓库地址
|
||
UPSTREAM_URL="https://github.com/Your/Upstream-Repo.git"
|
||
|
||
# 配置您需要保护的目录（如 config, assets 等），以空格分隔
|
||
PROTECTED_PATHS="config/ assets/ images/"
|
||
```
|
||
3. **赋予权限**: 运行 `chmod +x scripts/sync_from_upstream.sh`。
|
||
4. **初始化**: 第一次运行脚本时，它会自动为您创建 `upstream-main` 分支。
|
||
|