ruff

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ruff

Workflow

工作流程

Detect current Ruff version, Python targets, and existing lint/format tools.
Set one canonical Ruff configuration and inheritance strategy.
Select rule families in adoption layers to control migration noise.
Configure formatter behavior and notebook handling.
Integrate editor, pre-commit, and CI with version pinning.
Apply safe autofixes first, then isolate unsafe changes.
Tune cache and file discovery for monorepo-scale performance.

检测当前Ruff版本、Python目标版本以及已有的代码检查/格式化工具。
设置统一的Ruff配置和继承策略。
分阶段选择规则集，以控制迁移过程中的干扰。
配置格式化工具行为和笔记本文件处理方式。
集成编辑器、pre-commit和CI环境，并固定版本。
先应用安全的自动修复，再隔离处理不安全的变更。
调整缓存和文件发现机制，以适配单仓库规模的性能需求。

Preflight (Ask / Check First)

前期检查（先询问/确认以下内容）

Check whether the repo already uses
```
pyproject.toml
```
,
```
ruff.toml
```
, or
```
.ruff.toml
```
.
Check whether Black, Flake8 plugins, or isort are already enforced in CI.
Check target Python versions across runtime and tooling.
Check whether Jupyter notebooks are in scope for linting or formatting.
Check whether the team wants preview features or strict stability.

检查仓库是否已使用
```
pyproject.toml
```
、
```
ruff.toml
```
或
```
.ruff.toml
```
配置文件。
检查CI环境中是否已强制执行Black、Flake8插件或isort。
检查运行时和工具链对应的目标Python版本。
检查Jupyter笔记本是否需要纳入代码检查或格式化范围。
检查团队是否需要使用预览功能或严格的稳定版本。

Version and Stability Policy

版本与稳定性策略

Pin Ruff in CI and pre-commit because minor releases can include breaking changes.
Set
```
required-version
```
when deterministic behavior matters across contributors.
Keep
```
preview = false
```
by default.
Enable preview only in controlled trials and document rollback steps.
Prefer explicit upgrades with changelog review rather than floating latest.

在CI和pre-commit中固定Ruff版本，因为小版本更新可能包含破坏性变更。
当跨贡献者需要确定性行为时，设置
```
required-version
```
。
默认保持
```
preview = false
```
。
仅在受控测试中启用预览功能，并记录回滚步骤。
优先选择结合变更日志评审的显式升级，而非始终使用最新版本。

Canonical Configuration Pattern

标准配置模式

Keep one root config as the policy source of truth.
Use
```
extend
```
for subproject inheritance in monorepos.
Avoid duplicated rule lists in child configs unless divergence is intentional.
Set
```
target-version
```
explicitly for stable parsing and formatting behavior.
Use
```
src
```
and
```
respect-gitignore
```
to improve import classification and discovery.

Example baseline:

toml

[tool.ruff]
target-version = "py311"
line-length = 100
src = ["src"]
respect-gitignore = true
required-version = ">=0.15.1"

[tool.ruff.lint]
extend-select = ["I", "UP", "B", "SIM", "RUF"]
ignore = ["E501"]

[tool.ruff.format]
preview = false

保留一个根配置作为策略的唯一可信来源。
在单仓库中使用
```
extend
```
实现子项目继承。
除非有意差异化，否则避免在子配置中重复规则列表。
显式设置
```
target-version
```
以确保稳定的解析和格式化行为。
使用
```
src
```
和
```
respect-gitignore
```
来优化导入分类和文件发现。

示例基础配置：

toml

[tool.ruff]
target-version = "py311"
line-length = 100
src = ["src"]
respect-gitignore = true
required-version = ">=0.15.1"

[tool.ruff.lint]
extend-select = ["I", "UP", "B", "SIM", "RUF"]
ignore = ["E501"]

[tool.ruff.format]
preview = false

Rule Selection Strategy

规则选择策略

Start from Ruff defaults for high-signal correctness checks.
Add rule families in layers: imports, upgrades, bug-risk, simplifications.
Add docstring or complexity families only after team policy is clear.
Use
```
per-file-ignores
```
for tests, package
```
__init__.py
```
, and generated code.
Track suppressions and remove stale ignores during cleanup cycles.

从Ruff默认规则开始，这些规则是高价值的正确性检查。
分阶段添加规则集：导入规则、升级规则、风险规避规则、简化规则。
仅在团队策略明确后，再添加文档字符串或复杂度相关的规则集。
对测试文件、包的
```
__init__.py
```
和生成代码使用
```
per-file-ignores
```
。
跟踪抑制规则，并在清理周期中移除过时的忽略项。

Formatter Strategy

格式化工具策略

Choose one formatter owner for the repo.
Prefer
```
ruff format
```
when replacing Black for speed and single-tool consistency.
Avoid style rules that conflict with formatter ownership.
Exclude generated files and migration outputs from formatting.
Define notebook behavior explicitly if
```
.ipynb
```
files are tracked.
Treat notebooks as in-scope by default on modern Ruff; use
```
extend-exclude
```
or section-level excludes when opting out.

为仓库指定唯一的格式化工具负责人。
若要替换Black，优先选择
```
ruff format
```
以提升速度并保持工具一致性。
避免使用与格式化工具负责人策略冲突的样式规则。
将生成文件和迁移输出排除在格式化范围之外。
若仓库跟踪
```
.ipynb
```
文件，需显式定义笔记本文件的处理行为。
在新版Ruff中默认将笔记本纳入范围；若要排除，使用
```
extend-exclude
```
或按章节排除。

Autofix Safety and Change Control

自动修复安全性与变更控制

Run safe fixes first:
```
ruff check . --fix
```
.
Run unsafe fixes only in isolated PRs:
```
ruff check . --fix --unsafe-fixes
```
.
Review runtime and typing-sensitive diffs before merging unsafe fixes.
Avoid combining policy changes and mass autofix in one commit.
Keep modernization waves small enough for reviewers to reason about.

先运行安全修复：
```
ruff check . --fix
```
。
仅在独立的PR中运行不安全修复：
```
ruff check . --fix --unsafe-fixes
```
。
在合并不安全修复前，需审查对运行时和类型敏感的代码差异。
避免在一次提交中同时包含策略变更和大规模自动修复。
保持现代化改造的规模足够小，以便评审人员能够理解。

Monorepo and Inheritance Guidance

单仓库与继承指南

Use closest-config behavior intentionally.
Remember Ruff does not implicitly merge parent configs.
Use child
```
extend
```
references to preserve organization baseline.
Prefer
```
extend-select
```
over
```
select
```
in children unless resetting is intentional.
Keep package-specific deviations narrow and documented inline.

有意使用最近配置行为。
注意Ruff不会隐式合并父配置。
使用子配置的
```
extend
```
引用以保留组织的基准配置。
除非有意重置，否则在子配置中优先使用
```
extend-select
```
而非
```
select
```
。
保持包特定的差异化范围狭窄，并在代码中内联文档说明。

Editor, Pre-commit, and CI Integration

编辑器、Pre-commit与CI集成

Use Ruff language server integration where editor support is available.
Ensure editor and CI run compatible Ruff versions.
Set
```
force-exclude = true
```
if pre-commit passes explicit paths.
Run lint and format checks as separate CI steps for clearer failures.
Emit machine-readable output when CI annotations are required.

Suggested commands:

bash

ruff check .
ruff check . --fix
ruff format .
ruff check . --output-format=github

在支持的编辑器中使用Ruff语言服务器集成。
确保编辑器和CI运行兼容的Ruff版本。
若pre-commit传递显式路径，设置
```
force-exclude = true
```
。
将代码检查和格式化检查作为CI中的独立步骤，以便更清晰地定位失败原因。
当需要CI注解时，输出机器可读的格式。

建议使用的命令：

bash

ruff check .
ruff check . --fix
ruff format .
ruff check . --output-format=github

Performance Operations

性能优化操作

Keep
```
.ruff_cache
```
enabled for incremental speed.
Set
```
RUFF_CACHE_DIR
```
when workspace cache placement matters.
Restrict analyzed paths with
```
src
```
,
```
exclude
```
, and focused CI paths.
Avoid running repository-wide checks when change-scoped jobs are enough.
Profile slow runs before widening ignore patterns.

启用
```
.ruff_cache
```
以提升增量检查速度。
当工作区缓存位置重要时，设置
```
RUFF_CACHE_DIR
```
。
使用
```
src
```
、
```
exclude
```
和聚焦的CI路径来限制分析范围。
当变更范围的作业足够时，避免运行全仓库检查。
在扩大忽略模式前，先对缓慢的运行进行性能分析。

Migration Playbook

迁移手册

Baseline with
```
ruff check .
```
and record current diagnostics volume.
Introduce minimal rule expansion and fix low-risk issues first.
Enforce no-regression policy in CI before strict expansion.
Migrate formatter ownership in a dedicated PR.
Remove legacy linter plugins only after parity is validated.

以
```
ruff check .
```
为基准，记录当前的诊断数量。
先引入最小化的规则扩展，修复低风险问题。
在严格扩展规则前，在CI中执行无回归策略。
在专门的PR中迁移格式化工具的所有权。
仅在验证功能对等后，再移除旧的代码检查插件。

Failure Modes to Catch Early

需提前规避的失败场景

Mixing multiple formatters without clear ownership.
Resetting rule baselines accidentally in child configs.
Enabling preview features in CI without local parity.
Applying unsafe fixes without targeted review.
Letting ignore lists grow without cleanup ownership.
Assuming notebooks are excluded by default and silently linting/formatting them in CI.

在未明确负责人的情况下混用多个格式化工具。
在子配置中意外重置规则基准。
在CI中启用预览功能但本地环境未同步。
未进行针对性审查就应用不安全修复。
忽略列表不断增长但无人负责清理。
假设笔记本默认被排除，但在CI中悄悄对其进行代码检查/格式化。

Definition of Done

完成标准

Keep one canonical Ruff config with intentional inheritance.
Keep lint and format checks deterministic across local, pre-commit, and CI.
Pin Ruff versions and document upgrade cadence.
Enforce safe autofix by default and isolated unsafe migrations.
Keep suppressions small, explicit, and periodically reviewed.

保留一个统一的Ruff配置，并采用明确的继承策略。
确保本地、pre-commit和CI环境中的代码检查和格式化检查结果一致。
固定Ruff版本并记录升级节奏。
默认强制执行安全的自动修复，并隔离处理不安全的迁移。
保持抑制规则数量少、明确，并定期审查。

References

参考资料

```
references/ruff-2026-02-17.md
```

```
references/ruff-2026-02-17.md
```

Reference Index

参考索引

rg -n "Version|preview|required-version" references/ruff-2026-02-17.md

rg -n "extend|monorepo|closest config" references/ruff-2026-02-17.md

rg -n "rule|extend-select|per-file-ignores" references/ruff-2026-02-17.md

rg -n "formatter|Black|ruff format" references/ruff-2026-02-17.md

rg -n "cache|RUFF_CACHE_DIR|performance" references/ruff-2026-02-17.md

rg -n "pre-commit|CI|output-format" references/ruff-2026-02-17.md

rg -n "Version|preview|required-version" references/ruff-2026-02-17.md

rg -n "extend|monorepo|closest config" references/ruff-2026-02-17.md

rg -n "rule|extend-select|per-file-ignores" references/ruff-2026-02-17.md

rg -n "formatter|Black|ruff format" references/ruff-2026-02-17.md

rg -n "cache|RUFF_CACHE_DIR|performance" references/ruff-2026-02-17.md

rg -n "pre-commit|CI|output-format" references/ruff-2026-02-17.md