Peach: Local-first video metadata scraper and media manager.
ADR-0120:独立包更新对旧客户端的兼容门槛
背景
独立 Windows 包的在线更新由已装版本自己的代码完成:release_updates.check 读 releases.json 选包,选中应用更新包时由 update_packages.read_manifest 读包里的 update-manifest.json,再按清单复用或下载各工具包。这段代码装在用户机器上,发版时改不了。
0.42.0 到 0.47.3 的 read_manifest 要求清单里的工具集合与它认得的完全相等。0.48.0 往清单里加了人脸模型,这批客户端下载完 108 MB 的更新包后一律报「更新包工具清单无效」,只能手动装完整包。0.48.0 起的读法允许多出工具,但仍要求它认得的工具一个不少:哪天删掉一个工具,0.48.x 会以同样方式卡住。发布流程里没有任何一步拿旧客户端的代码去读新包,问题要等用户点了更新才暴露。
决策
一、清单按交集读。 客户端只准备自己认得、清单里也有的工具:清单多出的工具不下载,清单少了的工具视为新版本不再需要。旧客户端不认得的新工具装好后要由运行时自己补齐,这类工具登记在 update_packages.SELF_PROVISIONED(目前是人脸模型,缺失时由 face_models 下载)。
二、应用更新包用不了就改下完整包。 release_updates.check 同时给出同版本完整包的地址、大小与摘要。应用更新包的清单读不了、格式不认得或工具包校验失败时,standalone_update.prepare 改下完整包解压到同一个暂存目录。完整包自带全部工具,不经清单,所以以后清单格式再怎么变,这一版起的客户端都还有一条能走通的路。
三、发布门槛:旧版本的更新代码原样读新版本。 scripts/update_compat.py 对每个不早于 OLDEST_CLIENT、早于本版的版本标签,用 git archive 取出那一版的 src/peach,在独立进程里只导入那一版的 release_updates 与 update_packages,把网络换成本次的发布条目,核对三件事:
- 检查结果是有更新,并选中本版;
- 选中应用更新包时,读得了本版的工具清单;
- 清单里那一版不认得的工具都登记在
SELF_PROVISIONED。
有一个版本过不了就拒绝。门槛跑两处:tests/test_standalone_update.py 用打包代码合成的制品跑,改动在提交阶段就被拦下;标签流水线的 build-windows 在拆包后用真实制品再跑一遍,在任何文件上传之前。检出必须带发布标签,取不到旧版本标签时门槛失败,不跳过。
四、放弃旧客户端要显式改下限。 OLDEST_CLIENT 定为 0.48.0:0.47.3 及更早的版本要求工具集合完全相等,与 0.48 起的清单无法同时满足,只能手动装一次完整包。以后确需放弃一批客户端时,改这个常量,并在变更日志里写明受影响的版本与手动升级方法。
已拒绝方案
- 冻结清单的
tools为最初三项,新工具另起一个键:0.48.x 要求人脸模型在tools里,0.47.x 要求tools恰好三项,同一份清单两边无法同时满足;冻结只是把卡住的人从一批换成另一批。 - 只在文档里约定「清单只增不减」:这次的问题正是约定不在任何门槛里;
update_compat.py把约定写成拒绝。 - 在标签流水线里装上一版的独立包、实际跑一次升级:能多覆盖替换与迁移阶段,但旧客户端把检查地址写死为公开下载入口,没有可指向待发布制品的开关;取证成本高,留待替换阶段出现兼容问题时再做。替换阶段的助手由已装版本复制自身执行,新版本只提供暂存目录的内容,与清单无关。