From 9b9739ab611086f689c858f1079c1eb3a80bdfe6 Mon Sep 17 00:00:00 2001 From: Harvey Zhao Date: Thu, 10 Sep 2026 18:25:53 +0800 Subject: [PATCH] docs(refactor): [DOC-11] require next major versions for all packages --- AGENTS.md | 3 ++ refactor/README.md | 1 + .../2026-09-10-DOC-11-major-version-policy.md | 18 ++++++++ refactor/decisions.md | 1 + refactor/github-ci-cd.md | 2 +- refactor/plan.md | 14 +++--- refactor/progress.md | 8 +++- refactor/release-reviews.md | 2 + refactor/tasks.json | 28 +++++++++-- refactor/toolchain-release.md | 2 +- refactor/version-policy.md | 46 +++++++++++++++++++ 11 files changed, 111 insertions(+), 14 deletions(-) create mode 100644 refactor/changes/2026-09-10-DOC-11-major-version-policy.md create mode 100644 refactor/version-policy.md diff --git a/AGENTS.md b/AGENTS.md index a3ebf0fb9..e3bd306d2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,6 +29,9 @@ Each review fix remains a separate task and commit. Revalidate changed candidate The user explicitly includes GitHub CI/CD modernization in this refactor. Follow [refactor/github-ci-cd.md](refactor/github-ci-cd.md) for PR checks, regression matrices, artifacts, Pages and npm workflows. Distinguish local configuration from verified remote runs. +The user requires every workspace package to move to its own next major version for this +refactor (M.m.p -> (M+1).0.0). Follow refactor/version-policy.md; independent versions and +old API compatibility remain mandatory. This version policy is not publication authorization. ## Project Summary diff --git a/refactor/README.md b/refactor/README.md index b8b855453..53f7d83dc 100644 --- a/refactor/README.md +++ b/refactor/README.md @@ -26,6 +26,7 @@ | [docs 页面与编辑器测试](docs-browser-testing.md) | 复用已有 HTML、加载版本、隔离状态和补强文档 smoke | | [多轮复盘与 npm 准入](release-reviews.md) | Chrome 验证分工、三轮全局复盘、问题闭环和候选发布门槛 | | [工具链与发布](toolchain-release.md) | TypeScript、Bun、构建、版本管理和发布回退 | +| [全包大版本策略](version-policy.md) | 每包分别升级一个 major 的目标清单、兼容要求和版本落地步骤 | | [GitHub CI/CD](github-ci-cd.md) | PR/兼容矩阵、构建报告、Pages、npm 发布及远端准入验证 | | [AI 协作流程](ai-workflow.md) | AI 接续工作、任务边界、验证、记录和交接模板 | | [架构决策](decisions.md) | 已选方向、待验证方案及被拒绝方案 | diff --git a/refactor/changes/2026-09-10-DOC-11-major-version-policy.md b/refactor/changes/2026-09-10-DOC-11-major-version-policy.md new file mode 100644 index 000000000..fbae964f6 --- /dev/null +++ b/refactor/changes/2026-09-10-DOC-11-major-version-policy.md @@ -0,0 +1,18 @@ +# DOC-11 全包大版本升级策略 + +- 日期：2026-09-10；分支：`codex/compatible-modernization`。 +- 基线提交：`a9197f59`。 +- 提交主题：`docs(refactor): [DOC-11] require next major versions for all packages`。 +- 用户要求：所有包分别升级到自身下一大版本，如 5.4.1 → 6.0.0，插件同理。 + +## 交付 + +核对全部 22 个 workspace manifest，新增 version-policy.md 目标清单，替代旧的“不自动提升全部 major”表述。根指令、发布/CI/CD/复盘和决策同步；REL-01/02、CI-03、REVIEW-03 补充版本验收要求。 + +仅记录策略，未改 package.json、锁文件、历史基线或生成产物。各包独立版本与旧 API 兼容要求保留，不把主包版本套到全部插件。文档包也列入目标，npm 发布资格仍逐包核实；私有根工作区不作为 npm 发布包。 + +## 验证与后续 + +运行目标表与 22 个 manifest 的对应/major+1 断言、计划生成/依赖/覆盖/链接检查及 Git 差异检查。原 208 项任务 ID、范围、状态和依赖保持，新增 DOC-11 已完成；共 209 项任务，11 项规划完成，198 项待办。 + +没有运行生产或浏览器测试，没有推送、打 tag 或发布。下一项仍为 BASE-01；实际改版本由 REL-01/02 组织独立任务提交，候选测试之前生效。可独立回退本 DOC-11 文档提交，不影响生产代码。 diff --git a/refactor/decisions.md b/refactor/decisions.md index a76aab179..3302ceff5 100644 --- a/refactor/decisions.md +++ b/refactor/decisions.md @@ -23,6 +23,7 @@ | ADR-017 | 采用方向 | 分离准备工作、自动化验证与真实环境发布门槛 | 文档/本地候选不等待无关硬件；相关能力发布仍须真实证据，全项目任务范围不缩减 | | ADR-018 | 采用方向 | 历史失败台账与逐模块严格门槛 | 初始全包类型/环境不一定全绿；不掩盖既有问题、不允许新增回归，迁移包与发布范围严格验收 | | ADR-019 | 采用方向 | 候选产物内容绑定测试证据 | 来源 SHA、锁文件/工具和 tarball integrity 可追溯，内容变化后重新验证，避免测一份发布另一份 | +| ADR-020 | 采用方向 | 全部 workspace 包各自升级到下一个 major，minor/patch 归零 | 2026-09-10 用户明确要求；替代旧“不自动提升全部 major”策略，保留 independent、旧 API 及跨版本插件兼容；目标见 version-policy.md | ## 开始实现前需补齐的决定 diff --git a/refactor/github-ci-cd.md b/refactor/github-ci-cd.md index 1aa05c790..eb9c1c65f 100644 --- a/refactor/github-ci-cd.md +++ b/refactor/github-ci-cd.md @@ -41,7 +41,7 @@ required checks、环境审批、Pages source、npm trusted publisher 等是外 Pages 优先评估官方 artifact 部署流程，替代 CI 内提交/force push gh-pages 的耦合；先核对当前站点来源、域名、静态目录及保留文件，迁移前准备恢复旧部署方式的步骤。具体权限及 artifact 约束依据 [GitHub Pages workflow 文档](https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages)。尚未迁移远端设置时，旧站点仍须可恢复。 -npm 保持 Lerna independent 的分包版本，不自动统一版本或抬高 major。优先评估 [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) 的 OIDC 和 provenance；逐包核对支持环境、CLI 版本及信任配置，不能因支持 OIDC 就假定本仓库已配置。发布 CLI 环境要求不自动改变消费者最低 Node 要求。 +npm 保持 Lerna independent 的分包版本；用户已要求全部包分别升级到自身下一个大版本，按 [版本策略](version-policy.md) 校验版本清单，不把所有包统一为核心版本。优先评估 [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) 的 OIDC 和 provenance；逐包核对支持环境、CLI 版本及信任配置，不能因支持 OIDC 就假定本仓库已配置。发布 CLI 环境要求不自动改变消费者最低 Node 要求。 发布只接收明确受信任来源的候选 artifact，并核对源码 SHA、workflow run、包/版本/registry/tag 和 tarball integrity。不能执行任意外部 URL 提供的代码或仅凭 artifact 名称信任内容。避免发布阶段生命周期脚本悄悄重建包；若内容改变，重新验证。dry run 不能证明 npm 权限、OIDC 或真实发布成功。 diff --git a/refactor/plan.md b/refactor/plan.md index 963c98288..e6e7874e7 100644 --- a/refactor/plan.md +++ b/refactor/plan.md @@ -2,9 +2,9 @@ > 由 tasks.json 生成。请修改数据后运行 `node refactor/scripts/plan.mjs --write`，不要手改本表。 -基线：`40fcda6a37d0049d42e49c1e64e70d4fd9ba5f7f`。总任务 208 项，范围 22 个包及工作区/示例。 +基线：`40fcda6a37d0049d42e49c1e64e70d4fd9ba5f7f`。总任务 209 项，范围 22 个包及工作区/示例。 -状态：todo 198 / doing 0 / blocked 0 / done 10 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。 +状态：todo 198 / doing 0 / blocked 0 / done 11 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。 前置依赖是启动条件；验收是完成条件。任务可以继续拆分，但不能复用或悄悄删除旧 ID。 @@ -51,6 +51,7 @@ | DOC-08 | workspace
记录 Chrome 验证及多轮 npm 发布复盘 | DOC-07 | 浏览器分工、三轮复盘规范、发布依赖与接续文档 | 计划和发布依赖检查通过；独立提交 DOC-08，连接可用不冒充测试通过 | L | done | | DOC-09 | workspace
记录 docs HTML 与在线编辑器测试入口 | DOC-08 | 页面/加载方式、状态隔离、行为断言与既有任务映射 | 源码清点和计划检查通过，独立提交 DOC-09；不把页面存在当作测试通过 | L | done | | DOC-10 | workspace
记录 GitHub CI/CD 增强范围与验收 | DOC-09 | CI/CD 规范、四项实施任务与发布依赖 | 现有 workflow 核对、计划检查通过并独立提交；不冒充远端执行完成 | L | done | +| DOC-11 | workspace
记录全部包各自升级一个大版本 | DOC-10 | 22 包目标版本清单、决策和发布/CI/复盘规则同步 | 版本表与 manifest 对照、计划检查通过并独立提交；不修改旧 API 兼容要求 | L | done | ## 1 基线 @@ -86,7 +87,7 @@ | --- | --- | --- | --- | --- | --- | --- | | CI-01 | workspace
增强兼容矩阵、并发缓存与 CI 报告 | DOC-10, ENG-08, ENG-09, ENG-10 | OS/Node/TS/浏览器与影响范围矩阵、缓存、超时、汇总检查和 artifact 报告 | 固定安装、失败/取消不误报、核心影响全生态；检查只读，失败证据可追溯 | H | todo | | CI-02 | workspace
分离并改进 GitHub Pages 部署 | DOC-10, ENG-02, SITE-03 | Pages artifact 部署配置、旧路径/域名核对、预检和迁移恢复指南 | 部署只取受信任已验证产物；本地实现可验收，远端 source/环境和实际部署状态单独登记 | H | todo | -| CI-03 | workspace
建立 npm 分包候选与发布工作流 | DOC-10, CI-01, REL-08, REL-04 | 候选准备、精确 artifact 发布配置、OIDC 评估、版本/tag/registry 预检和部分失败恢复 | 不自动发布；明确逐包信任前置和 dry run 限制，不能重建未验证内容或重发冲突版本 | H | todo | +| CI-03 | workspace
建立 npm 分包候选与发布工作流 | DOC-10, CI-01, REL-08, REL-04 | 候选准备、精确 artifact 发布配置、OIDC 评估、版本/tag/registry 预检和部分失败恢复 | 不自动发布；明确逐包信任前置和 dry run 限制，不能重建未验证内容或重发冲突版本；按版本清单校验各包下一 major 和预发布/正式 tag，保留旧核心支持范围 | H | todo | | CI-04 | workspace
验收 GitHub 流水线与远端发布准入 | CI-01, CI-02, CI-03, SITE-06 | 静态/干净环境检查、真实 PR 正反例、候选 dry run、required checks/Pages/npm 必需配置状态及运维指南 | 必要 Actions 证据和远端配置核对齐全；缺失保持未完成，真实 publish/deploy 仍在授权发布步骤执行 | H | todo | ## 2.1 早期试点 @@ -379,8 +380,8 @@ | ID | 范围 / 步骤 | 前置依赖 | 交付物 | 验收条件 | 风险 | 状态 | | --- | --- | --- | --- | --- | --- | --- | | REL-08 | workspace
提前建立逐包发布准入台账 | BASE-08, ENG-07 | 每批包/版本/源码/锁文件/工具/tarball integrity、必需测试/设备证据、限制和回退映射 | 受影响能力缺证据明确阻止对应批次；无关批次可独立准备，旧证据在候选内容变化后失效 | H | todo | -| REL-01 | workspace
提前确定分包版本与差异方案 | REL-08, CORE-21, SITE-03, PKG-CHAPTER-04, PKG-AMBILIGHT-04, PKG-AUDIO-04, PKG-AUTO-THUMB-04, PKG-VTT-THUMB-04, PKG-HLS-04, PKG-DASH-04, PKG-MULTI-SUB-04, PKG-JASSUB-04, PKG-MASK-04, PKG-ASR-04, PKG-ADS-04, PKG-VAST-04, PKG-CAST-04, PKG-DPIP-04, PKG-CANVAS-04, PKG-IFRAME-04, PKG-TOOL-THUMB-04, PKG-DANMUKU-06, PKG-MB-08 | 每包版本/变更日志/依赖/类型差异方案和独立准入状态 | 所有包有方案和剩余门槛，未决项明确阻止相应发布；本步骤不声称已经可发布 | H | todo | -| REL-02 | workspace
生成候选 tarball 并验证新旧组合 | REL-01, CORE-22, ENG-07 | 各候选本地 tarball/integrity 与新旧核心/插件消费者验证报告，外部门槛单独标注 | 隔离安装和可自动化组合通过；设备结论不伪造，最终发布绑定同一候选内容 | H | todo | +| REL-01 | workspace
提前确定分包版本与差异方案 | REL-08, CORE-21, SITE-03, PKG-CHAPTER-04, PKG-AMBILIGHT-04, PKG-AUDIO-04, PKG-AUTO-THUMB-04, PKG-VTT-THUMB-04, PKG-HLS-04, PKG-DASH-04, PKG-MULTI-SUB-04, PKG-JASSUB-04, PKG-MASK-04, PKG-ASR-04, PKG-ADS-04, PKG-VAST-04, PKG-CAST-04, PKG-DPIP-04, PKG-CANVAS-04, PKG-IFRAME-04, PKG-TOOL-THUMB-04, PKG-DANMUKU-06, PKG-MB-08 | 每包版本/变更日志/依赖/类型差异方案和独立准入状态；按 version-policy.md 冻结各包下一 major（minor/patch 归零）并核实 registry 占用 | 所有包有方案和剩余门槛，未决项明确阻止相应发布；本步骤不声称已经可发布；全部包有 major 目标，版本冲突明确处理，独立准备任务同步 manifest/锁/依赖/日志 | H | todo | +| REL-02 | workspace
生成候选 tarball 并验证新旧组合 | REL-01, CORE-22, ENG-07 | 各候选本地 tarball/integrity 与新旧核心/插件消费者验证报告，外部门槛单独标注 | 隔离安装和可自动化组合通过；设备结论不伪造，最终发布绑定同一候选内容；在目标 major 版本确定后构建 pack，不在测试后改版本 | H | todo | | REL-03 | workspace
完成真机、外部 SDK 与压力验收 | REL-02, EX-03, SITE-06, MOD-05 | Safari/移动/PiP/Cast/IMA/模型/长播放完整报告 | 包集成与全项目真机/SDK/压力结论齐全才完成本汇总；独立批次先建立自己的完整门槛子任务 | H | todo | | REL-04 | workspace
提前演练回退与主线修复同步 | REL-08, ENG-07 | 分包旧版本/tag/依赖回退方案与 master 差异 | 隔离包演练可回退，主线修复同步流程可执行；正式每批再核对其实际回退产物 | H | todo | | REL-05 | workspace
经授权发布候选并收集反馈 | REL-03, REL-04, REVIEW-03 | 候选 tag、完整产物 integrity、反馈与复现记录 | 实际发布授权/操作/版本可追溯；本计划不自动执行发布 | H | todo | @@ -393,7 +394,7 @@ | --- | --- | --- | --- | --- | --- | --- | | REVIEW-01 | workspace
第一轮全项目架构与兼容性复盘 | REL-02, CORE-22, SITE-04, MOD-05, DOC-08 | 22 包结构、类型、旧 API/路径、测试盲区和维护文档的逐包报告 | 本轮阻断项由独立修复任务关闭并复测；环境缺口转交下一轮，不宣称已发布就绪 | H | todo | | REVIEW-02 | workspace
第二轮真实浏览器与生态集成复盘 | REVIEW-01, REL-03 | Chrome 交互、自动浏览器、新旧组合、真机/SDK/性能/资源的全范围报告 | 所需环境证据齐全，前轮修复再次核对；本轮阻断项关闭，无关 mock 不替代真实验收 | H | todo | -| REVIEW-03 | workspace
第三轮 npm 候选内容与发布准备复盘 | REVIEW-02, REL-04, CI-04 | 实际候选 integrity、干净安装构建/消费者、入口/许可/版本/tag/回退及前轮证据汇总 | 最终候选完整检查通过，发布阻断项为零；准备可审阅的批次报告，不自动执行 publish | H | todo | +| REVIEW-03 | workspace
第三轮 npm 候选内容与发布准备复盘 | REVIEW-02, REL-04, CI-04 | 实际候选 integrity、干净安装构建/消费者、入口/许可/版本/tag/回退及前轮证据汇总 | 最终候选完整检查通过，发布阻断项为零；准备可审阅的批次报告，不自动执行 publish；逐包核对 major 目标，不能用大版本豁免旧 API 兼容 | H | todo | ## 完成证据与阻塞 @@ -407,3 +408,4 @@ - DOC-08: [记录](changes/2026-09-10-DOC-08-browser-and-release-reviews.md) - DOC-09: [记录](changes/2026-09-10-DOC-09-docs-test-surfaces.md) - DOC-10: [记录](changes/2026-09-10-DOC-10-github-ci-cd.md) +- DOC-11: [记录](changes/2026-09-10-DOC-11-major-version-policy.md) diff --git a/refactor/progress.md b/refactor/progress.md index fa2c34699..46f5fba40 100644 --- a/refactor/progress.md +++ b/refactor/progress.md @@ -1,6 +1,12 @@ # 进度与证据 -## 当前阶段：DOC-10 GitHub CI/CD 规划 +## 当前阶段：DOC-11 全包大版本策略 + +2026-09-10，用户要求所有包各自升级到下一 major。已核对 22 个 manifest 并记录 [目标清单](version-policy.md)，同步发布/CI/复盘及根指令，详见 [DOC-11 记录](changes/2026-09-10-DOC-11-major-version-policy.md)。现有 209 项任务：11 项规划完成、198 项待办。 + +版本目标对应与计划/链接/依赖、Git 差异检查通过。仅修改文档，未改 manifest/锁文件或运行生产测试；旧 API 兼容要求不变。DOC-10 提交为 `a9197f59`，本轮独立提交 DOC-11。下一项仍为 BASE-01。 + +## 2026-09-10：DOC-10 GitHub CI/CD 规划 2026-09-10，用户明确纳入 GitHub CI/CD 优化。已核对现有 workflow 源码，新增 CI-01 至 CI-04 并接入第三轮发布复盘，文档见 [CI/CD 规范](github-ci-cd.md) 和 [DOC-10 记录](changes/2026-09-10-DOC-10-github-ci-cd.md)。现有 208 项任务：10 项规划完成、198 项待办；生产重构和 CI 改造均未开始。 diff --git a/refactor/release-reviews.md b/refactor/release-reviews.md index e5ce2954d..02cad670d 100644 --- a/refactor/release-reviews.md +++ b/refactor/release-reviews.md @@ -44,6 +44,8 @@ ## 发布关系 +REVIEW-03 必须逐包核对 [全包大版本目标](version-policy.md)、依赖范围、变更日志和候选标识；升级 major 不代表允许破坏旧调用或强制用户同时升级核心和插件。 + REVIEW-03 还依赖 CI-04，核对 [GitHub CI/CD](github-ci-cd.md) 的真实检查结果、候选来源和必要远端配置。只有 YAML 或本地 dry run 通过，不能声称 npm 发布权限及正式工作流已验证。 REVIEW-01 -> REVIEW-02 -> REVIEW-03 -> REL-05（经授权候选发布）-> REL-06（经授权正式发布）。REL-03 的真机验收与 REL-04 的回退演练继续保留；复盘不替代它们。代码迁移完成后仍需完成这些门槛。 diff --git a/refactor/tasks.json b/refactor/tasks.json index 0b6f85220..030c866d2 100644 --- a/refactor/tasks.json +++ b/refactor/tasks.json @@ -183,6 +183,24 @@ "changes/2026-09-10-DOC-10-github-ci-cd.md" ] }, + { + "id": "DOC-11", + "phase": "0 规划", + "title": "记录全部包各自升级一个大版本", + "scope": [ + "workspace" + ], + "dependsOn": [ + "DOC-10" + ], + "status": "done", + "risk": "L", + "deliverable": "22 包目标版本清单、决策和发布/CI/复盘规则同步", + "acceptance": "版本表与 manifest 对照、计划检查通过并独立提交；不修改旧 API 兼容要求", + "evidence": [ + "changes/2026-09-10-DOC-11-major-version-policy.md" + ] + }, { "id": "BASE-01", "phase": "1 基线", @@ -540,7 +558,7 @@ "status": "todo", "risk": "H", "deliverable": "候选准备、精确 artifact 发布配置、OIDC 评估、版本/tag/registry 预检和部分失败恢复", - "acceptance": "不自动发布；明确逐包信任前置和 dry run 限制，不能重建未验证内容或重发冲突版本", + "acceptance": "不自动发布；明确逐包信任前置和 dry run 限制，不能重建未验证内容或重发冲突版本；按版本清单校验各包下一 major 和预发布/正式 tag，保留旧核心支持范围", "evidence": [] }, { @@ -3526,8 +3544,8 @@ ], "status": "todo", "risk": "H", - "deliverable": "每包版本/变更日志/依赖/类型差异方案和独立准入状态", - "acceptance": "所有包有方案和剩余门槛，未决项明确阻止相应发布；本步骤不声称已经可发布", + "deliverable": "每包版本/变更日志/依赖/类型差异方案和独立准入状态；按 version-policy.md 冻结各包下一 major（minor/patch 归零）并核实 registry 占用", + "acceptance": "所有包有方案和剩余门槛，未决项明确阻止相应发布；本步骤不声称已经可发布；全部包有 major 目标，版本冲突明确处理，独立准备任务同步 manifest/锁/依赖/日志", "evidence": [] }, { @@ -3545,7 +3563,7 @@ "status": "todo", "risk": "H", "deliverable": "各候选本地 tarball/integrity 与新旧核心/插件消费者验证报告，外部门槛单独标注", - "acceptance": "隔离安装和可自动化组合通过；设备结论不伪造，最终发布绑定同一候选内容", + "acceptance": "隔离安装和可自动化组合通过；设备结论不伪造，最终发布绑定同一候选内容；在目标 major 版本确定后构建 pack，不在测试后改版本", "evidence": [] }, { @@ -3636,7 +3654,7 @@ "status": "todo", "risk": "H", "deliverable": "实际候选 integrity、干净安装构建/消费者、入口/许可/版本/tag/回退及前轮证据汇总", - "acceptance": "最终候选完整检查通过，发布阻断项为零；准备可审阅的批次报告，不自动执行 publish", + "acceptance": "最终候选完整检查通过，发布阻断项为零；准备可审阅的批次报告，不自动执行 publish；逐包核对 major 目标，不能用大版本豁免旧 API 兼容", "evidence": [] }, { diff --git a/refactor/toolchain-release.md b/refactor/toolchain-release.md index 888ed73e9..5ac4d43f3 100644 --- a/refactor/toolchain-release.md +++ b/refactor/toolchain-release.md @@ -60,7 +60,7 @@ GitHub CI/CD 的优化属于本次重构范围，按 [CI/CD 规范](github-ci-cd 1. BASE-01 确定旧核心和插件的支持矩阵，登记 npm tarball integrity。起点 SHA 不能代替消费者产物基线。 2. REL 阶段为每个发生变化的包生成候选 tarball，用隔离消费者验证，无需先公开发布。 -3. 决定独立版本号、变更日志和包依赖；纯内部兼容重构不自动提升全部包 major，也不自动把所有包改成同一版本。 +3. 按用户要求，全部 workspace 包各自升级一个大版本：M.m.p → (M+1).0.0，具体目标见 [版本策略](version-policy.md)。保留独立版本、同步变更日志和依赖范围；大版本升级不放宽旧 API 兼容要求。 4. 预发布 tag、npm 发布、站点部署及推送属于后续实际发布步骤；当前仅创建本地分支与文档，不执行这些动作。 5. 经授权后按风险批次发布候选版本。优先简单包，再核心兼容候选，最后高风险生态包；不要求用户同时升级整个生态。 6. 收集有复现步骤的反馈，与旧版本 A/B 对照。达到记录好的验收条件后才能更新正式 tag；不设无依据的自动等待天数。 diff --git a/refactor/version-policy.md b/refactor/version-policy.md new file mode 100644 index 000000000..1f6b6ab4f --- /dev/null +++ b/refactor/version-policy.md @@ -0,0 +1,46 @@ +# 全包大版本升级策略 + +2026-09-10 用户明确要求：本次重构所有 workspace 包分别升级到自身下一个大版本，M.m.p → (M+1).0.0。无论内部整理是否造成 breaking change，本次都按此策略发布；旧 API、类型、事件、DOM/CSS 和分发入口的兼容要求仍然成立。 + +## 目标清单 + +以下来自源码提交 a9197f59 的 22 个 package.json，是本次规划快照，并非已核实的 npm 最新版本；package-inventory.json 历史基线保持不变。本任务不修改 manifest。 + +| 包 | 当前源码版本 | 重构正式目标 | +| --- | --- | --- | +| artplayer | 5.4.1 | 6.0.0 | +| artplayer-plugin-ads | 2.1.0 | 3.0.0 | +| artplayer-plugin-ambilight | 1.1.0 | 2.0.0 | +| artplayer-plugin-asr | 2.1.0 | 3.0.0 | +| artplayer-plugin-audio-track | 1.1.0 | 2.0.0 | +| artplayer-plugin-auto-thumbnail | 1.1.0 | 2.0.0 | +| artplayer-plugin-chapter | 1.1.0 | 2.0.0 | +| artplayer-plugin-chromecast | 1.1.0 | 2.0.0 | +| artplayer-plugin-danmuku | 5.3.0 | 6.0.0 | +| artplayer-plugin-danmuku-mask | 1.1.0 | 2.0.0 | +| artplayer-plugin-dash-control | 1.1.0 | 2.0.0 | +| artplayer-plugin-document-pip | 1.1.0 | 2.0.0 | +| artplayer-plugin-hls-control | 1.1.0 | 2.0.0 | +| artplayer-plugin-jassub | 1.1.0 | 2.0.0 | +| artplayer-plugin-multiple-subtitles | 1.2.0 | 2.0.0 | +| artplayer-plugin-vast | 1.2.0 | 2.0.0 | +| artplayer-plugin-vtt-thumbnail | 1.1.0 | 2.0.0 | +| artplayer-proxy-canvas | 1.1.0 | 2.0.0 | +| artplayer-proxy-mediabunny | 1.2.0 | 2.0.0 | +| artplayer-tool-iframe | 1.1.0 | 2.0.0 | +| artplayer-tool-thumbnail | 4.4.0 | 5.0.0 | +| artplayer-vitepress | 1.1.0 | 2.0.0 | + +根 package.json 是 private 的 monorepo 管理包，当前 6.1.0，不作为 npm 发布包或核心版本依据。artplayer-vitepress 也按用户“所有包”要求列入版本升级；是否实际发布 npm 需按原分发范围和发布台账核实，不能因列入表中自动扩大公开发布范围。 + +## 规则与实施 + +1. 保持 Lerna independent：核心 6.0.0 不意味着全部插件也是 6.0.0。每个包 minor/patch 归零；本次只有一个 major 升级，不按任务或复盘轮次反复加 major。 +2. 允许在目标版本下准备预发布版本，例如 6.0.0-rc.1；具体标识由 REL-01 固定，正式目标保持 6.0.0。预发布、正式 tag 和实际 publish 仍遵循发布流程。 +3. REL-01 核实已发布历史及版本占用，再冻结分包目标、变更日志和依赖范围。若执行期间主线已经发布了目标 major 或存在目标版本，明确记录冲突并重新确定方案；不能覆盖已发布内容、悄悄改成 patch 或凭旧清单直接发布。 +4. REL-01/02 实施时先拆出可验收的版本准备任务，再同步 manifest、适用锁文件、内部 dependencies/peerDependencies、示例和变更日志，独立提交后构建候选。更新 peer 范围需保留已验证的旧核心支持，不因 major 变化强制全生态同步升级。 +5. 全包都纳入大版本目标，不以某包改动较少为由继续发原 minor/patch。允许按实际验证范围分批发布，未交付包保持待办，不伪造完成。 +6. 候选版本必须在最终构建/pack/验证前确定，CI-03 校验逐包版本、包内容和发布 tag；不能测试旧版本包后临发布再改版本。版本或依赖变化使相关候选证据失效，必须重跑验证。 +7. REVIEW-03 逐包核对目标、声明、入口、版本组合、旧调用及回退产物；release notes 说明本次工程重构采用新 major，但不能笼统声明所有旧 API 已兼容而缺少证据。 + +本次决定替代 toolchain-release.md 和 github-ci-cd.md 原先“不自动提升全部 major”的规则。兼容契约与三轮复盘门槛不变；这是版本策略记录，尚未实施升级或发布。