Skip to content

Latest commit

 

History

History
97 lines (69 loc) · 4.69 KB

File metadata and controls

97 lines (69 loc) · 4.69 KB

51 —— 受支持的版本与兼容性

**读者:**带着政策问题而来的人——一次评审流程、一次隔网构建、一个被钉住的版本。

**本章回答的那一个问题:**哪些发布受支持、支持多久,以及版本之间什么可以变、 什么不可以变。

**不在这里:**退出码表,那是 SPEC-003;机器输出的 schema,那是 50 —— 机器可读输出。

本文陈述哪些发布受支持、支持多久,以及版本之间允许发生什么变化。它的存在是因为 一个采用 mcpp 的工程会被自身的评审流程问到这些问题,而只存在于维护者脑子里的 答案无法被引用。

版本号

发布以 YYYY.M.D.N 命名——发布日期,加上当天发布的序号。这套方案的数字不携带 任何兼容性承诺:2026.9.4.1 不是 2026.9.3.2 的「小版本」。什么可以变、什么 不可以变,由下文陈述,而不是编码在版本号里。

支持范围

受支持 最新的一个发布
安全修复 最新的发布,以及上一个自然月的最后一个发布
不受支持 更旧的一切

发布是被取代,不是被撤回。更旧版本的已发布资产与索引条目保持原位,因为某个工程 可能钉住了其中一个,移除会破坏一个本来能正常构建的工程。

版本之间允许的变化

引擎自身各个接口的稳定性并不相同,这个差别值得精确陈述。

面 稳定性
mcpp.toml 的键 只增。既有键保持原有含义;无法识别的键会被报告,不会被静默忽略
CLI 命令与旗标 只增。被替换的拼写保留为别名
机器输出(--message-format json) 由 schemaVersion 版本化,见 50
build.mcpp 指令协议 版本化,见 kProtocolVersion。引擎遇到声明版本高于自身的程序会拒绝,而不是猜测
mcpp.lock 格式 由 schemaVersion 版本化;更旧的文件在读取时被迁移
目标表的行 只增。一行的档位可以上升;只要还有已发布的包以它为目标,该行就不会被移除
构建指纹、缓存布局、target/ 的内容 不是接口。 它们不经通知即变化,任何东西都不应解析它们

一个调用了自身引擎所带 mcpp 模块中不存在的函数的 build.mcpp,失败发生在 构建程序的编译阶段,而不是通过协议错误。协议号管的是线上的指令;类型化 API 由所装的引擎决定。两者都写在这里,是因为包作者看到的失败取决于他越过了哪一条边界。

复现一次构建

mcpp.lock 记录一次构建解析出的结果。--locked 断言当前解析与它一致,不一致 则失败,并点名发生变化的那个包:

error: --locked was given and this resolution differs from mcpp.lock:
         mcpplibs.cmdline 0.0.1 -> 0.0.2

发布构建、审计或 CI 作业应当传入 --locked。它会关闭构建快路径,因此该断言 总会执行。

锁尚不约束解析——它只记录并校验解析结果。把锁作为解析的输入来钉住结果,是对 解析器的另一项改动。

物料清单

mcpp emit sbom 写出一份描述已记录解析结果的 CycloneDX 1.5 文档:

mcpp emit sbom -o sbom.json

它读取 mcpp.lock 而不是重新解析,因为一份描述了与实际构建不同的依赖图的 文档,比没有文档更糟。许可证 mcpp 无法识别的组件会被写成 NOASSERTION 而不是 省略:缺失的字段读起来像「未检查」。

离线与隔网使用

--offline(或 MCPP_OFFLINE=1)会阻止一切网络访问:索引刷新、包下载与 工具链安装。需要其中之一的构建会点名自己所需要的东西并失败,而不是尝试联网。

报告问题

缺陷与安全报告提交到拥有该组件的仓库的 issue tracker——引擎、包索引,或者 包本身。一份点明了版本、宿主、目标与命令的报告是可处理的;缺了这四项的报告 通常会换来一次索要它们的回复。

当前边界

  • mcpp.lock 目前尚不约束解析。 它记录一次构建解析出的结果,--locked 核验新的解析与它一致;把锁作为解析的输入来钉住结果,是对解析器的另一项 改动。
  • SBOM 描述的是已记录的那次解析,而不是重新解析一次,因此在修改 manifest 之后、执行 mcpp update 之前写出的文档,描述的是更早的那张依赖图。
  • 许可证 mcpp 无法识别的组件会被写成 NOASSERTION 而不是省略,因为缺失的 字段读起来像「未检查」。