language-servers/ruff
1
0
Fork 0
mirror of https://github.com/astral-sh/ruff.git synced 2025-09-27 20:42:10 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2
ruff/docs/preview.md
Zanie Blue 316f75987d
Add explicit-preview-rules to toggle explicit selection of preview rules (#7390) 
Closes #7434 

Replaces the `PREVIEW` selector (removed in #7389) with a configuration
option `explicit-preview-rules` which requires selectors to use exact
rule codes for all preview rules. This allows users to enable preview
without opting into all preview rules at once.

## Test plan

Unit tests
2023-09-28 15:00:33 -05:00

2.4 KiB
Raw Blame History

Preview

Ruff includes an opt-in preview mode to provide an opportunity for community feedback and increase confidence that changes are a net-benefit before enabling them for everyone.

Preview mode enables a collection of newer rules and fixes that are considered experimental or unstable.

Enabling preview mode

Preview mode can be enabled with the --preview flag on the CLI or by setting preview = true in your Ruff configuration file (e.g. pyproject.toml).

Using rules that are in preview

If a rule is marked as preview, it can only be selected if preview mode is enabled. For example, consider a hypothetical rule, HYP001. If HYP001 were in preview, it would not be enabled by adding following to your pyproject.toml:

[tool.ruff]
extend-select = ["HYP001"]

It also would not be enabled by selecting the HYP category, like so:

[tool.ruff]
extend-select = ["HYP"]

Similarly, it would not be enabled via the ALL selector:

[tool.ruff]
select = ["ALL"]

However, it would be enabled in any of the above cases if you you enabled preview in your configuration file:

[tool.ruff]
extend-select = ["HYP"]
preview = true

Or, if you provided the --preview CLI flag.

To see which rules are currently in preview, visit the rules reference.

Selecting single preview rules

When preview mode is enabled, selecting rule categories or prefixes will include all preview rules that match. If you would prefer to opt-in to each preview rule individually, you can toggle the explicit-preview-rules setting in your pyproject.toml:

[tool.ruff]
preview = true
explicit-preview-rules = true

In our previous example, --select with ALL HYP, HYP0, or HYP00 would not enable HYP001. Each preview rule will need to be selected with its exact code, e.g. --select ALL,HYP001.

If preview mode is not enabled, this setting has no effect.

Legacy behavior

Before the preview mode was introduced, new rules were added in a "nursery" category that required selection of rules with their exact codes — similar to if explicit-preview-rules is enabled.

The nursery category has been deprecated and all rules in the nursery are now considered to be in preview. For backwards compatibility, nursery rules are selectable with their exact codes without enabling preview mode. However, this behavior will display a warning and support will be removed in a future release.