维护一个上游分支:每次同步大版本要动哪些地方

维护一个「跟着上游走、又带自己改动」的分支,最容易低估的不是冲突数量,而是上游顺手把你依赖的基础设施也改了。

这个月的一次上游同步可以当样本:5231 个文件、+21.6 万 / −61.1 万,看着吓人,但真正与本分支有交集的只有约 80 个文件、11 个内容冲突。冲突一个下午就解完了,剩下的时间全花在「上游把测试框架整个换掉」这件事上。

这篇按这次的实际顺序记一遍。

一、先量化规模,再决定怎么打

动手前先算出三个数字,它们决定策略完全不同:

指标 这次的值 意味着什么
上游改动规模 5231 文件 / +21.6 万 −61.1 万 是一次大重构,不是补丁
与本分支交集 约 80 个文件 冲突面可控
实际冲突 11 个内容冲突 一下午能解完

如果交集只有 80 个文件,就不要去做「全部 rebase 重放」——那是几千个文件的工作量。用 git merge 把这个上游版本整体合进来,只处理交集部分。

顺带一句:改动行数是负数(−61.1 万),说明上游删得比加得多。删除比新增更容易伤到你——删掉的文件可能是你分支里还在用的东西。

二、冲突好解,难的是「基础设施被换掉」

11 个冲突按常规处理:保留本分支的策略常量、品牌改动和自有发布链路,其余跟上游走。真正花时间的是三类「不算冲突但照样让你跑不起来」的变化。

① 测试命令直接消失。

上游删掉了 test:unit / test:unit:affected,连 scripts/run-affected-unit-tests.mjs 一起删了,改成 test:engineering 系列,并且——不再自动发现 packages/**/test,改由 scripts/engineering-test-files.json 这个显式清单管理。

后果很直接:本分支为了保住自己的策略和品牌断言而写的那些测试,不在清单里就等于从来没跑过。表现是「按新命令跑,全绿通过」——但你的测试一条都没执行。

修法是逐个确认本分支新增的测试文件,手动登记进清单。这一步没有报错提示,只能靠自己数。

② API 改名。

readRequestVerificationConfig 变成 readValidatedRequestVerificationConfig,还新增了 ApiError 类型。这种改名在 TypeScript 里会明确报错,好办;要小心的是只是行为变了、签名没变的那类。

③ 新增功能插进了你改过的位置。

上游在桌面更新流程里新增了 verifyWindowsAuthenticodeSignature,而这正是本分支「更新只走自有 Release」的改造点。合并时不显式保住 checkSelfHostedRelease 的分流,上游那套判断就会把你的分流顶掉——编译能过、类型也对,只是行为悄悄变回上游的。

这类「语义冲突」比文本冲突危险得多,只能靠合并后逐处复核改过的文件。

三、旧测试:删一部分,改一部分

上游既然重构了测试,本分支原有的测试自然有一批不兼容。这次共 13 个,分两类处理:

按上游退役删掉(9 个):

  • 7 个 UI 测试依赖 @testing-library/react,而上游把这个依赖移除了;
  • 1 个测的是「厂商更新链路」的就绪状态,而本分支已经明确关闭了那条链路——测的对象不存在了;
  • 1 个的旧断言假设「渲染进程自己判断 stale」,上游改成「由 Main 判断」,断言前提已经不成立。

改断言后保留(4 个):仍然有效的实现测试,按上游新行为逐个改。

关键判断:「不兼容」不等于「该删」。依赖被移除了、被测对象被关了,这是真该删;只是行为变了,就该改断言留下。

还有一条顺序上的讲究:如果一款文件同时是「上游删除、本地修改」,先保留本地版本,统一验证完再按退役逐批清理。一次性按上游删,会把本分支的策略覆盖丢光,而且丢了你也不知道——因为测试也一起没了。

四、拿不到日志时,怎么记遗留

发布这次没全绿:Build Linux-rpm-arm64 这个 job 失败。

gh run view --log-failed 拉日志超时,只能定位到「失败发生在容器内 pnpm install 阶段」,后面的打包、校验、收集产物全是 skipped。根因没查到。

这种时候的处理原则是:不猜,写清楚边界。

  • Release 说明不能写「Linux x64 与 arm64 均可用」——资产里确实缺 arm64 的 rpm;
  • 遗留条目要写清「哪一步失败、卡在哪个阶段、为什么没继续查、下轮怎么补」。

比”我以为只是网络抖动”要好得多:下一个看这条记录的人(通常是三个月后的自己)能直接接着查。

五、一条给下次的检查清单

同步完成后,除了「测试全绿」,还要确认这几件事:

  1. 测试真的跑了——新框架若是显式清单制,先数一遍本分支的测试有没有登记;
  2. 改过的文件逐个复核行为——尤其是被上游新增逻辑插进来的位置(更新流程、鉴权、配置读取);
  3. 上游新增的网络出口有没有接到你的策略门禁上——这次上游加了一个客户端配置下载边界,目前没有调用方,但将来一接入就会绕过本分支的「关闭官方远端配置」策略,必须提前登记成待办;
  4. 元数据别写错——同步记录的日期、版本号这种小地方,写错了会让下一个人误判范围(这次就把日期写成了一个月前);
  5. 产物清单要和发布说明对得上——少一个架构的包,说明里就不能说「双架构可用」。

六、仓库搬家:组织迁移后的权限与徽章

把主仓和两个发布源仓(Scoop manifest、Homebrew cask)一起迁到组织名下,踩到的都不是代码问题。

  • gh 没有 transfer 子命令:仓库转移只能走 GitHub API;
  • 迁移后跨仓推送立刻 403:Permission to <org>/scoop-zedg.git denied to <user>——fine-grained PAT 的授权绑定在旧仓库上,无法跨组织。解法不是重新签发 PAT,而是把更新逻辑搬进发布源仓库自身(update-manifest.yml / update-cask.yml,各用自身 GITHUB_TOKEN),主仓只负责触发;
  • 组织 Verified 徽章要求 Website 与已验证域名一致:只验证了根域 example.com,组织 Website 却填 https://www.example.com/,徽章不出现;改成根域后 is_verified:true;
  • 迁移后要全仓搜旧路径:README、docs、workflow 里的仓库地址、rebrand.py 的常量、release notes 生成器、rpm spec 的 URL——漏一处就会在下次发布时 404;
  • Secrets 不会跟着仓库转移:迁移后要逐项确认 workflow 引用的 secret 仍存在;残留的旧 secret 条目可以留,但没人读,容易误判。

做法:发布链路的跨仓写入尽量改成「目标仓库自更新」,比维护一个跨组织的 PAT 更稳。

七、上游把测试目录整个删掉之后

上一个上游版本(5099 文件、+42.9 万/−4.5 万)合并时,22 个冲突一下午解完,真正的工作量在测试:上游删掉了整个 packages/services/test/,本分支 11 个文件、164 个用例全红。

这不是「改 import」能解决的。同一批改动里,契约也换了:

  • 凭据接口从 key 变成 keys[];
  • 加密版本从 v1 升到 v2;
  • 新增批量 loadMany/updateMany/deleteUnreadable;
  • token 交换强制要求 data.user.user_id;
  • 会话键新增 zai_cn/session_revision/linked_bigmodel;
  • codingPlan 必须提供 loadOAuthAccountMaterial。

测试只能按新契约逐类重写。最后 204 个文件 / 1524 个用例全绿,但这一步没有任何捷径——上游删测试 ≠ 你的测试可以删,凡是被删掉的目录里测过、而你分支还依赖的行为,都得在新框架下重新表达。

几个具体坑:

  • 匿名工单用例拿不到 token、列表为空:上游把匿名身份迁到凭据键 zcodefeedbackaccesstoken,list() 无 token 直接返回空且不发请求;mock 只认旧键 zcodefeedbackclientid,saveIfAbsent 也不落盘。另外 list() 不显式设 method,mock 里 init?.method === "GET" 永远不成立,要改成 !init?.method || init?.method === "GET";
  • 合并后 lint 告警从 84 跳到 539:不是代码回归,而是上游新增了 .oxlintrc.json 的 React Hooks override,首次全仓扫描集中暴露。对照基线树确认 0 error 即可;
  • 品牌文案 43 处遗留:上游新文案写的是原品牌名,跑一遍 apply-brand-naming.py --write,复检干净即可;
  • 批量改写测试的脚本自身会出错:engineering-test-files.json 合并后括号与排序被破坏,JSON 解析失败。批量改文件后先校验结构;
  • 缺 macOS 产物时,补发不如全量重发:上一个版本 release 只出 10 个资产(macOS job 被取消),补发工作流也未必一次成功;最终放弃补发、全量重发下一个版本,12 个资产齐全,旧版转 draft;
  • pre-push 钩子找不到 pnpm:git push 报 exit 127,因为 pnpm 在 ~/.local/share/pnpm、不在 hook 的 PATH。PATH="$HOME/.local/share/pnpm:$PATH" git push 即可,不必改钩子;
  • 两个 workflow 并发推 main 必然非快进:定时统计 workflow 在另一个 workflow 运行期间推了 README,后者 push 报 ! [rejected] HEAD -> main (fetch first)。checkout 要 fetch-depth: 0,push 前 git fetch + git rebase;而每次全量重写的清单文件必然冲突,rebase 时采用本次生成版本继续。

八、跨大版本迁移 fork:不要合并已分叉的主分支

另一个 fork 停在 1.4.7,定制只有 6 个提交,而上游主分支比它多 180 个提交——两条历史早就分叉了。这种情况下「把定制分支合并回上游主干」是个伪需求:

  • 合并会把 180 个上游提交与 6 个定制提交揉成一个巨大的 merge commit,以后再跟上游就永远要解这一坨;
  • 正确做法是基于上游目标 tag 新建分支,再把定制提交 cherry-pick 过来。6 个提交里 1 个因为上游已包含同一修复、应用后无改动,确认后跳过。

迁移过程里几个具体问题:

  • 配置键会跨 crate 搬家:1.5.0 把 hbb_common::config::keys::OPTION_* 移到了 base crate,cherry-pick 后代码编译失败。改用文件已导入的 keys::...,行为不变,单独补一个适配提交。
  • Release 全平台失败但没有任何编译错误:唯一非成功作业是 iOS cancelled(iOS 需要额外签名,发布步骤本来就被注释掉)。把 iOS job 设为 if: False 直接跳过,重推 tag 后全作业成功。
  • 删主分支不会减小仓库体积:本地对象从 90M 压到 33M,GitHub 仍显示 76MB——被删分支的提交仍是当前分支的祖先,对象仍被引用;只有重写历史才能回收,而重写会丢掉上游完整历史,不值得。
  • gh 会默认解析到 upstream:本地同时配了 fork 与 upstream 时,所有查询要显式 -R <your-fork>,否则看到的是上游的 CI 状态。
  • rebase 不会改发布参数:上游新版本把发布步骤写成 prerelease: true,rebase 后依然如此。每次同步后都要逐项核对 draft/prerelease。
  • 定时 workflow 会自动建分支:推送后 origin 多出一个 auto-update-* 分支,是依赖更新任务创建的,不属于定制分支,删掉即可。

本机验证不了就写清楚:RustDesk 需要 vcpkg 与 libyuv,本机没有,只能核对符号、导入路径与 diff,把编译验证交给 Release CI——这条限制要写进记录,避免下一个人误以为本地能跑。

总结

跟着上游走的分支,维护成本不在「解冲突」,在这三件事:

  • 上游会改你的基础设施——测试怎么跑、怎么发现,比业务代码更影响你;
  • 语义冲突比文本冲突危险——编译通过、测试通过,行为却变回上游的;
  • 拿不到证据时,把边界写清楚,不要用推测填补空白。

一句话:同步大版本之后,先验证「你的测试还在跑」,再验证「测试全绿」。