Files
marqdo-cli/docs/MARQDO_3_0_PRERELEASE_PLAN.md
cflmy 9e76635028
ci/woodpecker/push/main Pipeline was successful
Linux strict security lane (G-C) / strict isolation escape matrix (push) Canceled after 0s
CI / fmt + clippy + test (Linux x86_64) (push) Canceled after 0s
CI / schema instance validation + consumers (push) Canceled after 0s
CI / runtime contract (macos-latest) (push) Canceled after 0s
CI / runtime contract (windows-latest) (push) Canceled after 0s
CI / release evidence manifest (push) Canceled after 0s
CI / release candidate artifact (macos-latest) (push) Canceled after 0s
CI / release candidate artifact (ubuntu-latest) (push) Canceled after 0s
evidence(3.0.0-beta.1): same-SHA gates, release record and exact status links
Records the tagged SHA 2c7c4f31e7 evidence:
same-SHA Woodpecker pipeline #37 PASS (including archive build + cold-install
smoke), fixed-node G4 #38 MEASURED/WARN with 9/9 correctness, the same-SHA
disposable-VM strict G3 PASS, the frozen-binary external conformance manifest
(7/7 categories, unchanged CLI hash), and the archive-only clean-install smoke.

Adds docs/evidence/ci/<sha>/manifest.json in the explicit beta profile
(BETA_RELEASE_CANDIDATE), the strict evidence JSON/log, the G4 report, the
release gate record, the third-party handbook validation matrix/log, and the
user-facing 3.0.0-beta.1 release notes. Updates STATUS, COMPATIBILITY, CURRENT,
CHANGELOG, README, security-gate and the prerelease plan to the exact released
SHA, tag, release URL and archive hashes. No source code changes after the tag.
2026-11-22 02:55:19 +08:00

121 lines
13 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# RFC-REL-0001 — Marqdo 3.0 预发布路线、发布门禁与 LTS 策略(建议草案)
> 状态:**Adopted as the release policy for `3.0.0-beta.1`**(2026-11-22,源码 `2c7c4f31e7a388d3fcfa717a77067e696ed13854`,[release](https://git.cflmy.cn/cflmy/marqdo-cli/releases/tag/v3.0.0-beta.1))。REL-01~REL-05 已按本文实施;实际门禁结果记录在 `docs/STATUS.md`、`docs/evidence/` 和 `docs/evidence/ci/<release-sha>/manifest.json`。
> 代码核对基线(提议时):`cflmy/marqdo-cli@56189b176c612bf399ff965c3b642077f6b04617`,2026-11-22;§2 的“剩余门禁”表是迁移前快照,当前事实以 `docs/STATUS.md` 为准。
> 现有发布依据:`docs/releasing.md`、`docs/STATUS.md`、`COMPATIBILITY.md`、`spec/extension-selection.md`、`spec/callable-resolution.md`。
> 本文是策略与门禁定义;**tag 只能在该 SHA 的全部门禁通过后创建**,本文本身不构成任意 SHA 的发布批准。
## 1. 产品定位和版本结论
- 旧 `cflmy/marqdo` 已发布至 `v2.9.1`,新的 `marqdo-cli` 是同一品牌下的**语言重实现与破坏性架构更新**,不是旧 CLI 的逐项兼容升级。
- 公开产品版本可从 `3.0.0-beta.1` 起步;`3.0.0` 不带后缀应留给稳定版。Rust 工作区、CLI `--version`、Analysis `producer.version`、Tool 版本协商均应反映该版本。
- 使用一个仓库作为 3.x 官方主实现;旧仓库保留历史与迁移链接,**不声称源文件、插件 ABI、lockfile 兼容**。
- 正式提供持续维护承诺之前,不应把任何 Beta 或 RC 称为 LTS。建议待稳定的 `3.0.0`、`3.1.x` 实际使用数据验证后,再考虑把 `3.2.x` 设为第一条 LTS;是否能以此命名取决于质量门禁,而不是预定日历。
## 2. 已核实事实与剩余门禁
| 事项 | 基线证据 | 结论 |
|---|---|---|
| 语言执行语义 | RFC-LANG-0002、ADR-0052、现有测试 | 已实现、破坏性,不允许旧语法自动降级 |
| 外部插件与 Provider | ADR-0054~0058、`spec/resource-provider-v2.md`、`spec/extension-selection.md` | 核心路径已实现;Provider Worker 仅宣称 Linux x86_64 |
| 独立扩展验收 | `docs/evidence/extension/6a7bb983.../manifest.json`:7 项 PASS | 证据只绑定旧 SHA `6a7bb98`,需在发布提交重跑 |
| CI | `actions/runs/44928442709`,SHA `56189b1` | Linux、Windows、macOS 各运行契约 PASS;tag 发行包任务因未打 tag 而 SKIPPED |
| strict/G3 | `actions/runs/44928442715` 查询时 queued;本地隔离 VM 历史 PASS | 发布 SHA 缺远程 G3 证据;不可声称整个 strict 已认证 |
| G4 | `docs/evidence/2026-11-21-perf-woodpecker-agent-1.md` | 9/9 结果正确,固定 agent 两次 5 warmup / 20 样本;共享 powersave 环境,WARN、旧 SHA |
| 公开版本 | `Cargo.toml` 仍为 `0.1.0`,若干工具兼容样例 `<1` | 3.0.0-beta 发布前必须迁移验证 |
| 第三方入门 | README 有扩展示例、`spec/` 有协议;Tool v1 标头仍称 Proposed,plugin spec 某段称 Native only | 需要整合并去除失效状态文本 |
## 3. 两套必须明确分开的发布策略
### 3.1 Beta(允许明确声明的非安全性缺口)
目标平台为 **Linux x86_64**;其他平台的核心 CLI 测试结果可以公开说明,但不默认提供支持声明。所有清单要公开写明平台、功能和限制。
**不可豁免的 Beta 门禁:**
1. 在清洁、固定的同一提交(发布 SHA)上:`cargo fmt --all -- --check`、`cargo clippy --workspace --all-targets -- -D warnings`、`cargo test --workspace --locked`、`cargo build --release --locked -p marqdo-cli -p marqdo-provider-worker` 全部通过。
2. GitHub 最新同 SHA 的 Linux 主 CI PASS;发布产物中 `marqdo` 与同平台 `marqdo-provider-worker` 同目录,不允许只打包 CLI。
3. 冻结 CLI 的外部仓库黑盒验收在**发布 SHA**重新执行,至少 pure pinned-Git 包、Callable Worker、陌生 Foreign Kernel、Provider v2、Tool/Analysis/Trace、权限负例及工件改动负例全部 PASS;生成并校验 `docs/evidence/extension/<SHA>/manifest.json`。
4. 冷安装、离线 `--version`/`--help`、`check/run/call`、lock/sync、Tool 安装与分发、Provider Worker 启动、错 SHA/错目标/未授权拒绝全部由发布归档中的**实际二进制**完成;不得依赖开发源码目录。
5. **不得虚假宣传安全隔离。** 发布包若保留并开放 Linux `strict`,必须有该 SHA 的真实 G3 隔离负例证据;若暂无证据,需采用明确经过测试的 fail-closed 禁用方式并在公告中写 `strict: unsupported`。不允许仅改 README 却继续将未验证的 `strict` 描述为安全保障。Beta 的这一策略必须经维护者明确签字并由 CI 可复查。
6. G4 基准不得造假;若当期固定节点仍是 WARN,可由维护者批准 **Beta-only WARN** 并公开环境和限制;必须通过 9 个正确性基准,不允许数值漂移或已确认的灾难性回退。
7. 明确产品版本 `3.0.0-beta.1` 与协议独立版本;工具 SemVer 协商在真实测试版上可安装、拒绝不兼容范围、不会误把 `<1` 当成支持 3.x。
8. `README`、`CHANGELOG`、`COMPATIBILITY`、`docs/STATUS`、`docs/releasing`、协议入口页、迁移说明,均更新至同一事实基线;无“未实现却声称已发布”或“已实现仍称 Proposed”的矛盾。
9. 不发布未经实际构建/烟测的平台二进制;产物附 SHA256、SOURCE_SHA、构建工具链信息和已知限制。
**可延期至后续 Beta 或稳定版:** Windows Native/Worker ABI、macOS Provider Worker、strict L2、uv/npm 自动建环境、分布式 registry、JIT、内置 Knowledge/Proof/View、成熟异步/并发模型、未经承诺的平台安装包。明确注明项目默认 `project` 模式不是 OS 沙箱,Worker 也不是完整沙箱。
### 3.2 Stable / LTS(不可用 Beta 例外替代)
- Stable `3.0.0`:在公开支持的 Linux 平台上所有承诺功能有安全/兼容/性能证据;公开协议与变更策略清楚;有迁移说明和至少一次真实使用者反馈周期。平台可继续限定 Linux,不要求通过虚假的“全平台 LTS”门禁。
- LTS(建议后续 `3.2.x`):冻结 `.mq.md` 语言语义、Analysis/Trace/Tool/Plugin/Provider 各自协议主版本和 lockfile 契约;提供安全修复流程、回归 CI、外部仓库兼容矩阵、从 3.0 及 2.9 迁移材料、发布渠道与公告模板。
- LTS 应提前承诺支持窗口(建议至少 12 个月,实际长短由维护资源决定),定义安全补丁与非破坏性修复回移规则,明确 API/ABI 哪些会不兼容;不因开发完成某一里程碑自动称 LTS。
- 默认不为旧 `cflmy/marqdo` 的历史语法或旧插件 ABI 建隐性兼容层。需要迁移的由独立迁移工具、教程和示例承担。
## 4. 3.0.0-beta.1 之前建议拆分的 5 个短 PR
**REL-01:全仓版本线迁移(强制)**
- 将 Cargo workspace 包的产品版本改为 `3.0.0-beta.1`,更新 Cargo.lock 与 crate 编译产物;不必将 *独立协议版本*、依赖包版本、官方 stdlib 版本一并改为 3。
- 扫描 `0.1.0`、`>=0.1,<1`、`M0.5`、`pre-1.0` 等在发行说明、JSON schema consumer、Tool fixture、示例、CI 中是 **产品版本**还是 **独立包/协议版本**。逐项更新,严禁盲目全局替换。
- `project.marqdo` 目前文档注明仅 informational;为未来稳定兼容,建议在 Beta 之前增加**显式版本范围的检查**,最少在不兼容时发出清晰诊断并在 Beta 正式版前确保 fail-closed;编写对应正负测试。如果无法实现,必须写明 Beta 不保证该字段生效。
- 为使用 `semver::VersionReq` 的 Tool manifest 添加 `>=3.0.0-beta.1,<4.0.0` 等真实候选测试,并确保带预发布后缀的版本匹配符合 SemVer 语义。
**REL-02:测试版支持矩阵与安全策略(强制)**
- 发布声明只选自己真实能够测试和修复的平台。建议首发 Linux x86_64,其他平台根据可运行烟测增列为 Experimental。
- 为 `strict` 选择:A. 当 SHA 的 G3 真实通过则在 Linux 标为实验性 probe-gated;B. 若无,则构建/配置和端到端测试保证 **fail closed**,公开标为不支持。禁止“默默降级到 project”。
**REL-03:全量发行归档与冻结二进制(强制)**
- `cargo build --release --locked -p marqdo-cli -p marqdo-provider-worker`。
- 打包 `marqdo` + `marqdo-provider-worker`、文档/许可证/协议/必要示例,清洁目录安装后测试;两者同目标 triple、版本、来源 SHA;检查归档 SHA256。
- 在干净外部仓库重复黑盒套件,证据绑定发行 SHA 和精确二进制 hash;至少做未授权和工件篡改的消极测试。
**REL-04:开发者入口文档(强制)**
- `docs/developers/README.md`、`quickstart.md`、`tools.md`、`libraries.md`、`extensions.md`、`analysis-trace.md`、`compatibility.md`;与 `spec/` 的规范性协议以链接方式衔接,避免复制分叉契约。
- 设置 `marqdo view/knowledge/prove` 作为 Tool 使用的示例,并将其作为外部仓库模板,而不是 CLI 内置命令。
- 修复 `spec/tool-v1.md` 的 Proposed 状态和 `spec/plugin-abi.md` 的 Native-only 旧说法;修复旧版发布指令、样例 version、已过时的 G3/G4 状态。
**REL-05:Beta Release Candidate 审批(强制)**
- 切 release candidate SHA,再跑所有必需门禁,不在验证期间继续修改同一版本的内容;必要变更形成下一 SHA 并重跑。
- 将稳定版发布策略与 Beta 策略分别标记和自动验证,不用一个 `DO_NOT_RELEASE` 字段悄悄代表两种不同门槛。
- 维护者明确批准 `v3.0.0-beta.1` 标签和 GitHub prerelease(`prerelease: true`),不要把测试版误当正式发布或 LTS。保留回滚/撤回方案与已知限制。
## 5. 建议的版本线(条件性,不是承诺日程)
| 版本 | 目的 | 进入条件 |
|---|---|---|
| `3.0.0-beta.1` | 发布真正可运行、可接第三方库的新语言基线 | 上述 Beta gate 全绿或明确允许的非安全性 WARN |
| `3.0.0-beta.2` | 修复外部消费者、协议示例及安装包问题 | 跨仓回归全部 PASS,收集第一轮外部反馈 |
| `3.0.0-rc.1` | 冻结最小公共契约和平台支持范围 | 不再新增破坏语义;发布契约全部文档化 |
| `3.0.0` | 3.x 稳定版 | 公开承诺范围内的 release gate 完整 PASS |
| `3.1.x` | Tools/Knowledge/View/Proof 实际生态检验 | 外部仓库无核心改动迭代,公共协议更成熟 |
| `3.2.x LTS`(候选) | 长期支持分支 | 真实跨版本兼容证明、安全更新流程、明确维护窗口 |
**建议首先冻结而不强求全部功能成熟的内容**:RFC-LANG-0002 的语义;Analysis v2、Trace v2、Tool v1、Plugin ABI v1、Provider v2、lock v4 的**当前定义**。未来不兼容修改应提升**对应协议版本**,不能因为产品叫 3.0 就把所有协议号写成 3。
## 6. 发版前必须人工审阅的风险
- 原始 `docs/releasing.md` 按稳定版执行,对 Beta 需要新增经批准的 `prerelease` profile,不能在脚本中硬关门禁。
- GitHub Push CI 成功但 Release Artifact job 因没有 tag/workflow_dispatch 而跳过,属于正常条件流程,不是产物已验证。
- 当前冻结二进制外部证据绑定 `6a7bb98`,与最新 `56189b1` **不一致**,需重跑。
- 原始 `spec/tool-v1.md` 文件标头仍写 Proposed(源码已实现);`spec/plugin-abi.md` 第 9 节开头仍声称“Native only”;README 开头仍保留旧里程碑状态与测试数字。公共入口不能带这些明显冲突。
- 版本从 0.x 改 3.0 prerelease 后,插件 manifest `plugin.version` 与产品 version、官方 stdlib version、协议 schema version 并不是同一个版本轴;必须在发布和升级说明中画清楚。
- 第三方 GitHub/GitLab/Gitea 源、工具二进制和 Provider SHA256 只能验证内容完整性,不提供出版者身份保证;不能把它当签名来源认证。
## 6.1 实施状态(3.0.0-beta.1)
| 条目 | 状态 | 落点 |
|---|---|---|
| REL-01 版本线迁移 | 已实施 | workspace/CLI/Analysis `3.0.0-beta.1`;`project.marqdo` 强制校验;工具预发布 SemVer 正负测试 |
| REL-02 支持矩阵与 strict 策略 | 已实施 | Linux x86_64 支持;macOS/Windows 实验性不声称;strict 同 SHA VM 证据或 fail-closed 策略记录在 STATUS |
| REL-03 发行归档与冻结二进制 | 已实施 | `tools/release/package.py`、`tools/release/smoke.py`;归档含 CLI+worker、SOURCE_SHA、RELEASE_INFO、KNOWN_LIMITATIONS |
| REL-04 开发者入口文档 | 已实施 | `docs/developers/`、修正后的第三方接入手册、spec 状态清理 |
| REL-05 Beta RC 审批 | 已实施 | `tools/ci/release_evidence.py --profile beta`、`v3.0.0-beta.1` tag/prerelease、rollback 与已知限制 |
## 7. 最终判定公式
Beta = `同 SHA 主 CI PASS` + `同 SHA 冻结二进制外部扩展 PASS` + `Linux 安装包 PASS` + `版本兼容 PASS` + `清晰支持矩阵` + `严格安全门禁(G3 实证或 strict fail-closed 禁用)` + `维护者批准`。
Stable = 上述条件 + 所承诺功能的完整安全/性能门禁 + 公共接口与迁移政策冻结。
LTS = Stable + 已经历真实生态版本迭代 + 可持续的安全补丁/兼容性维护承诺。