深入解析 Ruff 的版本管理策略自定义版本方案、Preview 模式与稳定化机制【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff导读Ruff 是一款用 Rust 编写的极速 Python 静态检查工具linter与代码格式化工具formatter。在其 API 尚未稳定之前Ruff 采用了一套自定义的版本方案用minor 版本号承载破坏性变更、用patch 版本号承载 bug 修复并配套 Preview预览模式、规则与修复的稳定化流程以及一套服务于 VS Code 扩展的独立版本区分规则。本文以仓库官方文档 docs/versioning.md 为骨架结合源码逐一拆解这套版本策略的每一项约定帮助你准确判断某个升级是否可能破坏现有配置、理解新规则与新修复的引入节奏以及正确使用 preview 模式参与社区反馈。一、总体设计为什么 Ruff 不直接使用语义化版本Ruff 目前采用自定义版本方案核心约定是minor次版本号用于引入破坏性变更breaking changespatch修订号用于修复 bug和向后兼容的增量改进major主版本号尚未使用。Ruff 目前没有稳定的 API一旦 API 稳定将切换到完整的语义化版本SemVer方案。也就是说在当前阶段0.x.y中的xminor承担了传统语义化版本中 major 的角色——升级 minor 版本时应当预期可能发生破坏性变化而升级 patch 版本通常可以安全进行。二、Crate 版本策略哪些 crate 遵循正常策略Ruff 以 Cargo workspace 形式组织代码见 Cargo.toml 中的[workspace]与[workspace.dependencies]配置各 crate 独立发布。根据官方策略只有以下三个 crate 遵循 Ruff 的正常版本策略ruff对应 crates/ruffruff_linter对应 crates/ruff_linterruff_wasm对应 crates/ruff_wasm需要特别注意即使这三个 crate 遵循正常版本号其 Rust 接口也不遵循语义化版本。也就是说依赖这些 crate 的 Rust 程序无法通过版本号判断 API 是否兼容。其余随 Ruff 一起发布的 crate如ruff_python_parser、ruff_python_ast、ruff_python_formatter、ruff_diagnostics、ruff_text_size等不提供任何稳定性保证它们的 Rust 接口被视为内部实现、不稳定它们统一以0.0.x版本发布每发布一次 Ruff 版本这些 crate 的 patch 号就递增一次无论 crate 本身是否有任何改动。在 Cargo.toml 的[workspace.dependencies]中可以观察到这一现象当前仓库中ruff与ruff_linter的版本为0.16.6而ruff_cache、ruff_db、ruff_diagnostics、ruff_python_parser等大量内部 crate 均为0.0.12。三、Minor 版本何时会发生破坏性变更官方明确列出以下情况将触发minor 版本号提升移除某个已废弃deprecated的选项或特性配置发生向后不兼容的变化——文档特别说明在1.0.0之前这类变更可能出现在 minor 版本中但一般应尽量避免对某类新文件类型的支持被提升为稳定stable停止支持某个已进入生命周期终点EOL的 Python 版本Linter 相关某条规则被提升为稳定某条稳定规则的行为被改变包括稳定规则的作用范围被显著扩大规则的意图intent发生变化注意遵循规则原始意图的 bug 修复不属于此类稳定规则被加入默认启用集合default set稳定规则被从默认启用集合中移除某条规则的 safe fix 被提升为稳定某条规则被废弃deprecatedFormatter 相关稳定格式化风格stable style发生变化Language server 相关移除某个已有能力capability移除某个已废弃的 server 设置。简而言之升级 minor 版本前务必阅读 changelog 与迁移指南。仓库根目录的 BREAKING_CHANGES.md 以及 CHANGELOG.md、changelogs 目录下的分版本 changelog如 0.16.x 等各系列都可用于核对每个版本的实际变更。四、Patch 版本哪些变化是安全的以下情况触发patch 版本号提升这类升级通常不会破坏既有配置修复 bug包括为修复 bug 而改变行为这类行为修正被明确允许在 patch 中发生以向后兼容的方式新增配置选项不产生格式化变化也不产生新的 lint 错误新增对某个 Python 版本的支持在 preview 模式下新增对某类文件类型的支持废弃deprecate某个选项或特性注意废弃与移除不同移除属于 minor 变更Linter 相关为规则新增 unsafe fix在 preview 模式下为规则新增 safe fix在 preview 模式下扩大规则的作用范围降低某个 fix 的适用性applicability在 preview 模式下新增规则改变某条 preview 规则的行为Formatter 相关稳定风格发生变化但仅限于修复以下问题防止生成无效语法、改变程序语义或删除注释preview 风格发生变化Language server 相关新增对某个新能力的支持新增 server 设置废弃某个 server 设置。由此可见patch 升级中行为变化的空间被严格限定要么是 bug 修复要么是 preview 模式下的实验性调整要么是保证语义等价与注释安全的格式化修正。这与第一节的总体设计完全一致。五、最低支持的 Rust 版本MSRV编译 Ruff 所需的最低 Rust 版本MSRV记录在仓库根目录 Cargo.toml 的[workspace.package]段落的rust-version键中该值可能在任意一次发布minor 或 patch中变化。当前仓库中该值为[workspace.package] edition 2024 rust-version 1.96官方对 MSRV 的约束是永远不会比最新稳定 Rust 版本新出超过 2 个版本。即如果最新稳定 Rust 是1.85则 Ruff 的 MSRV 至多为1.83公式MSRV ≤ N-2N 为最新稳定版本。这一点只对从源码构建 Ruff 的用户有意义。从 Python 包索引PyPI安装 Ruff 通常安装的是预编译二进制不需要本机编译 Rust。因此普通用户一般无需关注 MSRV只有自行执行cargo build --release等源码构建流程时才需要确保本机 Rust 工具链版本满足要求。Rust 工具链版本由仓库根目录的 rust-toolchain.toml 约束。六、Preview 模式提前体验不稳定能力6.1 设计意图Ruff 提供了preview预览模式用于启用新的、尚未稳定的规则与特性例如对某类新文件类型的支持。官方文档明确了 preview 模式的两个定位目的收集社区反馈确认改动是净收益net-benefit定位边界它不是用来限制未完成的工作或我们很可能移除的特性。但官方同时保留了重要权利可以更改任何由 preview 模式门控的行为包括直接移除 preview 特性或规则。这意味着 preview 模式下的任何规则、修复或风格都不具备稳定性承诺升级时可能随时变动。6.2 配置入口与源码实现在配置中preview是一个布尔开关。从 crates/ruff_workspace/src/configuration.rs 的源码可以看到配置解析后映射到PreviewMode枚举定义于 crates/ruff_linter/src/settings/types.rs取值为Enabled/Disabledpreview既可以在全局层级配置self.preview也可以在lint、format、analyze等子配置块中单独覆盖子配置未设置时回退到全局值如lint.preview.unwrap_or(global_preview)全局 preview 开启时还会联动影响文件包含/排除模式的默认集合INCLUDE_PREVIEW并在规则表解析、格式化器 preview 风格、analyze 的 preview 行为等多个环节生效。典型的启用方式以pyproject.toml为例[tool.ruff] preview true若只想让 linter 或 formatter 单独启用预览可以分别在对应子块设置[tool.ruff.lint] preview true [tool.ruff.format] preview true此外源码中大量以is_*_enabled(settings)命名的辅助函数见 crates/ruff_linter/src/preview.rs为每条具体规则独立判断 preview 是否生效。该文件的文档注释说明了一个设计巧思这些命名函数便于在规则从 preview 提升到 stable 时直接删除函数然后让 Rust 编译器指出所有需要清理的调用点。七、规则稳定化Rule Stabilization流程官方对新规则与既有规则的处理遵循以下指导原则新规则必须先在 preview 模式下引入新规则至少要在 preview 模式中停留一个 minor 版本才能被提升为 stable。文档给出的关键示例若规则在 patch 版本0.6.1加入则最早要到0.8.0才具备稳定化资格因为0.6.1的下一个 minor 是0.7.0而0.6.1所在 minor 序列的下一 minor计数规则要求跳过0.7.0直接看0.8.0稳定规则的行为不应在 patch 版本中被显著改变规则的稳定化可能被延迟以便将多条规则打包进同一次 minor 发布批量提升并非所有 preview 规则都必须在某次 minor 发布中完成提升。这套流程解释了为什么 Ruff 的 changelog 中经常出现将若干规则从 preview 提升为 stable的批量条目——这正是第 4 条策略的体现。结合上一节的 preview 机制规则的生命周期可以概括为新增preview→ 至少一个 minor 版本观察 → 可批量提升为 stable。八、修复稳定化Fix Stabilization三级适用性Ruff 的自动修复fix分为三个适用性级别级别含义何时应用Display显示永不应用仅展示给用户仅作为提示展示Unsafe不安全需要用户显式选择加入后才应用可能不是用户本意或可能改变运行时行为 / 删除注释Safe安全可以自动应用确定符合用户意图或保持代码语义不变这套模型在源码中有精确对应Applicability枚举定义于 crates/ruff_diagnostics/src/fix.rs第 14–32 行三个变体DisplayOnly、Unsafe、Safe的文档注释与上表语义一致并且Fix::applies通过self.applicability applicability的比较来决定某级别下该修复是否生效。关于修复稳定化的版本约定修复可以以较低适用性引入随后提升到更高适用性如 Unsafe → Safe降低某个修复的适用性不构成破坏性变更因此出现在 patch 升级的合法变更清单中某个修复的适用性可能因preview 模式开启与否而变化。对照第三节、第四节的清单可以看到为规则新增 unsafe fix、在 preview 下新增 safe fix、降低 fix 适用性都属于 patch 变更而将某个 safe fix 提升为 stable 则属于 minor 变更。九、VS Code 扩展的特殊版本方案VS Code 官方对扩展的 pre-release预发布支持存在限制具体见 VS Code 扩展发布文档中关于 prerelease extensions 的说明。为了在不依赖 pre-release 标签的情况下区分稳定版与预览版Ruff 采用了偶数/奇数 minor 版本号方案稳定版minor 版本号使用偶数例如2024.30.0、2024.32.0、2024.34.0……预览版minor 版本号使用奇数例如2024.31.0、2024.33.0、2024.35.0……。这与 Ruff 主程序0.x.y的版本号体系相互独立仅用于 VS Code 扩展的发布渠道管理。对于希望在 VS Code 中优先体验新规则/新特性的用户可以选择奇数 minor 的扩展版本。十、实践要点小结结合本文的全部约定面向不同角色的使用建议可以归纳为普通用户通过 pip/uv/Homebrew 等安装预编译包升级patch版本通常安全但仍建议阅读 changelog因为修复 bug 的行为变化被允许在 patch 中发生升级minor版本前重点核对 BREAKING_CHANGES.md 与对应版本的 changelogs确认是否存在配置变更、稳定规则行为改变或 EOL Python 版本停止支持等破坏性变更不需要关心 MSRV除非从源码自行编译。希望提前验证新规则的开发者在配置中开启preview true但需要接受 preview 规则/行为随时可能变动甚至被移除的事实不要将其作为长期依赖。规则与修复的贡献者新规则一律从 preview 引入修复按 Display → Unsafe → Safe 的适用性阶梯推进Safe 的提升属于 minor 变更规则稳定化至少等待一个 minor 版本并可批量进行。VS Code 用户偶数 minor 为稳定渠道、奇数 minor 为预览渠道按需选择。通过理解这套版本约定你就能把 Ruff 的每次升级风险控制在可预期的范围内并充分利用 preview 模式参与到新特性的反馈与验证中。参考文档与源码路径本文主体依据docs/versioning.mdMSRV 定义Cargo.toml[workspace.package].rust-version当前为1.96版本号信息生成crates/ruff/src/version.rsVersionInfo与 git 提交信息格式化Preview 配置解析crates/ruff_workspace/src/configuration.rs、crates/ruff_linter/src/settings/types.rsPreview 门控辅助函数crates/ruff_linter/src/preview.rsFix 适用性枚举crates/ruff_diagnostics/src/fix.rs历史变更记录CHANGELOG.md、changelogs、BREAKING_CHANGES.md【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
