Rust 标准库语义化版本Semver破坏性检查cargo-semver-checks 在 rustc-dev-guide 中的完整实践【免费下载链接】rustEmpowering everyone to build reliable and efficient software.项目地址: https://gitcode.com/GitHub_Trending/ru/rust导读本文围绕 rustc-dev-guide 中《Standard library semantic versioning breakage check》一篇系统讲解 Rust 编译器仓库如何借助cargo-semver-checks下称 c-s-c在 CI 上对core、alloc、std三大标准库 crate 做 API 级语义化版本破坏性检测。你将掌握该检查的五种运行结果及对应处置、stamp 文件src/bootstrap/stdlib-semver-check-stamp的升级机制以及如何通过./x test std-semver-check在本地手动复跑整个检查流程。一、检查机制概述用 rustdoc JSON 对比两次提交的 APIRust 仓库中的 CI jobtest-x86_64-gnu-stdlib-semver-check专门负责标准库的 semver 破坏性检查。它的核心思路是对被合并的父提交parent merge commit与当前待合并提交分别生成标准库的 rustdoc JSON 输出用cargo-semver-checks工具对比两份 JSON 中core、alloc、std三个 crate 的公开 API发现任何非预期的破坏性变更即视为检查失败。其中父提交的 rustdoc JSON并非本地生成而是直接下载 CI 预构建的rust-docs-json组件。从 download.rs 的实现可以看到bootstrap 会以rust-docs-json-{version}-{target}.tar.xz为文件名、以ci-docs-json为组件 key从 CI 构件服务器下载对应提交的文档 JSON并解压出share/doc/rust/json目录作为 baseline见 test.rs。当前提交的 JSON 则由 bootstrap 调用 in-tree 的doc::Std构建步骤、以DocumentationFormat::Json方式现场生成。二、五种运行结果与对应处置文档明确列出了 c-s-c 运行后可能出现的五种情况每种都有明确的工程处置路径情形含义处置1一切正常c-s-c 未发现任何破坏无需操作测试通过2近期 rustdoc JSON 版本被升级c-s-c 尚不支持测试以成功结束仅打印需要更新 c-s-c的警告等 c-s-c 发布支持新 JSON 格式的版本后自动回到情形 13c-s-c 报告了破坏但属于误报在 t-libs 的 Zulip 主题中报告误报并 bump stamp 文件见下节4c-s-c 报告了真实破坏帮你发现了非预期的 API 变更修复问题也可在 Zulip 主题中同步成功案例5c-s-c 报告了真实破坏但你仍希望合入例如该变更已通过 FCP 的边界场景bump stamp 文件需要特别说明的是情形 2CI job 目前直接安装 c-s-c 的最新 release 版本因此不需要在rust-lang/rust仓库中手工维护其版本号JSON 格式的适配完全跟随上游工具发布节奏。从底层实现看test.rs 对每个 crate 都会执行一次cargo semver-checks子进程并依据退出码分流0无破坏正常通过101c-s-c 无法解析 JSON 数据对应JSON 版本过新的降级路径打印告警但不视为致命错误100检测到 semver 破坏在fail_fast模式下直接exit_process(1)否则记入延迟失败列表其他退出码视为工具本身运行失败直接终止。三、bump stamp 文件显式承认破坏性变更当 PR 中确实存在 c-s-c 能检测出的破坏无论真伪且你希望 CI 保持绿色时唯一要做的是修改 src/bootstrap/stdlib-semver-check-stamp 这个 stamp 文件并在文件末尾更新对应的 PR 号。其文件头注释明确写道Change this file to explicitly acknowledge making a breaking change to the Rust standard library. If this file is modified in the same PR as the breaking change, then CI will not fail due to the breaking change being detected by cargo-semver-checks.也就是说stamp 文件是一种显式确认机制一旦该文件随 PR 被修改测试就恒为绿色无论 c-s-c 检测到什么。对应的 CI 短路逻辑位于 test.rs当 bootstrap 判定当前运行于 CI 环境且src/bootstrap/stdlib-semver-check-stamp相对上游基线存在变更通过has_changes_from_upstream检查时直接打印Skipping stdlib semver check, because src/bootstrap/stdlib-semver-check-stamp was modified.并提前返回。这保证了破坏性变更 显式确认的组合不会卡住合并。四、本地手动运行检查文档给出的手动命令为./x test std-semver-check --set rust.stdlib-semver-baseline${PARENT}其中${PARENT}是希望作为对比基线的提交 SHA若省略该参数bootstrap 会自动从本地 git 历史中选取最近的 upstream 提交作为基线。对应的 bootstrap 配置项定义在 config/toml/rust.rsstdlib-semver-baseline commit-sha在 test.rs 中StdSemverCheck::make_run会先取config.stdlib_semver_baseline配置值若未配置则调用build_helper::git::get_closest_upstream_commit寻找最近的 upstream 父提交——找不到或出错时分别以No baseline parent commit found for std-semver-check与Cannot get baseline parent commit for std-semver-check直接 panic。此外手动运行前还需满足一个前提本机必须已安装cargo-semver-checks。check_if_cargo_semver_checks_is_installedtest.rs会执行cargo semver-checks --version探测未找到时会提示cargo-semver-checks was not found, please install it并中止避免无工具硬跑。命令别名本身也有测试守护bootstrap 的 CLI 路径快照测试 x_test_semver_check.snap 及对应用例 cli_paths/tests.rsx_test_semver_check, test std-semver-check确保了x test std-semver-check这个别名长期可解析。五、检查覆盖范围与参数细节c-s-c 的调用参数可以从 test.rs 中完整还原cargo semver-checks -Z unstable-options --stability-aware --release-type minor --current-rustdoc build-dir/crate.json --baseline-rustdoc baseline/share/doc/rust/json/crate.json要点解读对core、alloc、std三个 crate 逐一执行日志前缀为Checking semver compatibility of crate--stability-aware启用稳定性感知即尊重#[stable]/#[unstable]属性标注来判定破坏--release-type minor表示按次要版本发布的语义规则检查即当前库的补丁版本更新不应带来破坏当前与基线分别使用两份 rustdoc JSON二者均来自同一套{crate}.json命名约定保证对比口径一致。六、给标准库贡献者的实用建议综合文档与实现标准库贡献者在日常开发中可遵循以下决策路径推送 PR 后关注test-x86_64-gnu-stdlib-semver-check是否转红若失败且是误报到 t-libs 的 Zulip 频道Breakages detected by cargo-semver-checks 主题反馈并 bump stamp 文件让 CI 恢复绿色若失败且是真实破坏且不应发生修复代码这通常意味着 API 设计有遗漏若失败且是真实破坏但确需合入如已走完 FCP在 PR 中同步修改 stamp 文件并填写 PR 号作为显式留档。整个过程无需手工维护工具版本——CI 始终使用最新 release 的 c-s-c——因此标准库团队需要关注的只是变更是否破坏 API、以及是否显式承认这一核心决策。相关实现全部位于 src/bootstrap/src/core/build_steps/test.rs约 L4754-L4891 的StdSemverCheck步骤可作为深入阅读的起点。【免费下载链接】rustEmpowering everyone to build reliable and efficient software.项目地址: https://gitcode.com/GitHub_Trending/ru/rust创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Rust 标准库语义化版本（Semver）破坏性检查：cargo-semver-checks 在 rustc-dev-guide 中的完整实践
Rust 标准库语义化版本Semver破坏性检查cargo-semver-checks 在 rustc-dev-guide 中的完整实践【免费下载链接】rustEmpowering everyone to build reliable and efficient software.项目地址: https://gitcode.com/GitHub_Trending/ru/rust导读本文围绕 rustc-dev-guide 中《Standard library semantic versioning breakage check》一篇系统讲解 Rust 编译器仓库如何借助cargo-semver-checks下称 c-s-c在 CI 上对core、alloc、std三大标准库 crate 做 API 级语义化版本破坏性检测。你将掌握该检查的五种运行结果及对应处置、stamp 文件src/bootstrap/stdlib-semver-check-stamp的升级机制以及如何通过./x test std-semver-check在本地手动复跑整个检查流程。一、检查机制概述用 rustdoc JSON 对比两次提交的 APIRust 仓库中的 CI jobtest-x86_64-gnu-stdlib-semver-check专门负责标准库的 semver 破坏性检查。它的核心思路是对被合并的父提交parent merge commit与当前待合并提交分别生成标准库的 rustdoc JSON 输出用cargo-semver-checks工具对比两份 JSON 中core、alloc、std三个 crate 的公开 API发现任何非预期的破坏性变更即视为检查失败。其中父提交的 rustdoc JSON并非本地生成而是直接下载 CI 预构建的rust-docs-json组件。从 download.rs 的实现可以看到bootstrap 会以rust-docs-json-{version}-{target}.tar.xz为文件名、以ci-docs-json为组件 key从 CI 构件服务器下载对应提交的文档 JSON并解压出share/doc/rust/json目录作为 baseline见 test.rs。当前提交的 JSON 则由 bootstrap 调用 in-tree 的doc::Std构建步骤、以DocumentationFormat::Json方式现场生成。二、五种运行结果与对应处置文档明确列出了 c-s-c 运行后可能出现的五种情况每种都有明确的工程处置路径情形含义处置1一切正常c-s-c 未发现任何破坏无需操作测试通过2近期 rustdoc JSON 版本被升级c-s-c 尚不支持测试以成功结束仅打印需要更新 c-s-c的警告等 c-s-c 发布支持新 JSON 格式的版本后自动回到情形 13c-s-c 报告了破坏但属于误报在 t-libs 的 Zulip 主题中报告误报并 bump stamp 文件见下节4c-s-c 报告了真实破坏帮你发现了非预期的 API 变更修复问题也可在 Zulip 主题中同步成功案例5c-s-c 报告了真实破坏但你仍希望合入例如该变更已通过 FCP 的边界场景bump stamp 文件需要特别说明的是情形 2CI job 目前直接安装 c-s-c 的最新 release 版本因此不需要在rust-lang/rust仓库中手工维护其版本号JSON 格式的适配完全跟随上游工具发布节奏。从底层实现看test.rs 对每个 crate 都会执行一次cargo semver-checks子进程并依据退出码分流0无破坏正常通过101c-s-c 无法解析 JSON 数据对应JSON 版本过新的降级路径打印告警但不视为致命错误100检测到 semver 破坏在fail_fast模式下直接exit_process(1)否则记入延迟失败列表其他退出码视为工具本身运行失败直接终止。三、bump stamp 文件显式承认破坏性变更当 PR 中确实存在 c-s-c 能检测出的破坏无论真伪且你希望 CI 保持绿色时唯一要做的是修改 src/bootstrap/stdlib-semver-check-stamp 这个 stamp 文件并在文件末尾更新对应的 PR 号。其文件头注释明确写道Change this file to explicitly acknowledge making a breaking change to the Rust standard library. If this file is modified in the same PR as the breaking change, then CI will not fail due to the breaking change being detected by cargo-semver-checks.也就是说stamp 文件是一种显式确认机制一旦该文件随 PR 被修改测试就恒为绿色无论 c-s-c 检测到什么。对应的 CI 短路逻辑位于 test.rs当 bootstrap 判定当前运行于 CI 环境且src/bootstrap/stdlib-semver-check-stamp相对上游基线存在变更通过has_changes_from_upstream检查时直接打印Skipping stdlib semver check, because src/bootstrap/stdlib-semver-check-stamp was modified.并提前返回。这保证了破坏性变更 显式确认的组合不会卡住合并。四、本地手动运行检查文档给出的手动命令为./x test std-semver-check --set rust.stdlib-semver-baseline${PARENT}其中${PARENT}是希望作为对比基线的提交 SHA若省略该参数bootstrap 会自动从本地 git 历史中选取最近的 upstream 提交作为基线。对应的 bootstrap 配置项定义在 config/toml/rust.rsstdlib-semver-baseline commit-sha在 test.rs 中StdSemverCheck::make_run会先取config.stdlib_semver_baseline配置值若未配置则调用build_helper::git::get_closest_upstream_commit寻找最近的 upstream 父提交——找不到或出错时分别以No baseline parent commit found for std-semver-check与Cannot get baseline parent commit for std-semver-check直接 panic。此外手动运行前还需满足一个前提本机必须已安装cargo-semver-checks。check_if_cargo_semver_checks_is_installedtest.rs会执行cargo semver-checks --version探测未找到时会提示cargo-semver-checks was not found, please install it并中止避免无工具硬跑。命令别名本身也有测试守护bootstrap 的 CLI 路径快照测试 x_test_semver_check.snap 及对应用例 cli_paths/tests.rsx_test_semver_check, test std-semver-check确保了x test std-semver-check这个别名长期可解析。五、检查覆盖范围与参数细节c-s-c 的调用参数可以从 test.rs 中完整还原cargo semver-checks -Z unstable-options --stability-aware --release-type minor --current-rustdoc build-dir/crate.json --baseline-rustdoc baseline/share/doc/rust/json/crate.json要点解读对core、alloc、std三个 crate 逐一执行日志前缀为Checking semver compatibility of crate--stability-aware启用稳定性感知即尊重#[stable]/#[unstable]属性标注来判定破坏--release-type minor表示按次要版本发布的语义规则检查即当前库的补丁版本更新不应带来破坏当前与基线分别使用两份 rustdoc JSON二者均来自同一套{crate}.json命名约定保证对比口径一致。六、给标准库贡献者的实用建议综合文档与实现标准库贡献者在日常开发中可遵循以下决策路径推送 PR 后关注test-x86_64-gnu-stdlib-semver-check是否转红若失败且是误报到 t-libs 的 Zulip 频道Breakages detected by cargo-semver-checks 主题反馈并 bump stamp 文件让 CI 恢复绿色若失败且是真实破坏且不应发生修复代码这通常意味着 API 设计有遗漏若失败且是真实破坏但确需合入如已走完 FCP在 PR 中同步修改 stamp 文件并填写 PR 号作为显式留档。整个过程无需手工维护工具版本——CI 始终使用最新 release 的 c-s-c——因此标准库团队需要关注的只是变更是否破坏 API、以及是否显式承认这一核心决策。相关实现全部位于 src/bootstrap/src/core/build_steps/test.rs约 L4754-L4891 的StdSemverCheck步骤可作为深入阅读的起点。【免费下载链接】rustEmpowering everyone to build reliable and efficient software.项目地址: https://gitcode.com/GitHub_Trending/ru/rust创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考