Skip to content

armgit / peach

Public Imported from GitHub
0

Peach: Local-first video metadata scraper and media manager.

3.9 KB
Raw Blame

ADR-0120:独立包更新对旧客户端的兼容门槛

  • 状态:已采纳
  • 日期:2026-10-24
  • 关系:补充 ADR-0012 的更新边界与 ADR-0119 的发布门槛

背景

独立 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,把网络换成本次的发布条目,核对三件事:

  1. 检查结果是有更新,并选中本版;
  2. 选中应用更新包时,读得了本版的工具清单;
  3. 清单里那一版不认得的工具都登记在 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 把约定写成拒绝。
  • 在标签流水线里装上一版的独立包、实际跑一次升级:能多覆盖替换与迁移阶段,但旧客户端把检查地址写死为公开下载入口,没有可指向待发布制品的开关;取证成本高,留待替换阶段出现兼容问题时再做。替换阶段的助手由已装版本复制自身执行,新版本只提供暂存目录的内容,与清单无关。