mirrors/ruff
1
0
Fork 0
mirror of https://github.com/astral-sh/ruff.git synced 2025-08-04 02:38:25 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

Improve documentation of the preview mode (#10168)

Browse source 
## Summary

This PR was prompted by the discussion in #10153.
It adds CLI tab examples next to the `pyproject.toml` and `ruff.toml`
examples. It should be helpful for users wanting to try out the preview
mode without modifying or creating a `.toml` file.
It also adds a paragraph to try to make the effect of the preview mode
less confusing.
This commit is contained in:
Hoël Bagard 2024-03-05 12:08:30 +09:00 • committed by GitHub
parent 72599dafb6
commit d441338358
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 43 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

49
docs/preview.md
View file

@ -3,8 +3,9 @@
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 lint rules, fixes, and formatter style changes that are
considered experimental or unstable,.
Preview mode enables a collection of unstable features such as new lint rules and fixes, formatter style changes, interface updates, and more. Warnings about deprecated features may turn into errors when using preview mode.
Enabling preview mode does not on its own enable all preview rules. See the [rules section](#using-rules-that-are-in-preview) for details on selecting preview rules.
## Enabling preview mode
@ -27,6 +28,13 @@ Preview mode can be configured separately for linting and formatting (requires R
preview = true
```
=== "CLI"
```console
ruff check --preview
```
To enable preview style formatting without enabling any preview lint rules:
=== "pyproject.toml"
@ -43,11 +51,16 @@ To enable preview style formatting without enabling any preview lint rules:
preview = true
```
=== "CLI"
```console
ruff format --preview
```
## 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
config file:
hypothetical rule, `HYP001`. If `HYP001` were in preview, it would _not_ be enabled by adding it to the selected rule set.
=== "pyproject.toml"
@ -63,6 +76,13 @@ config file:
extend-select = ["HYP001"]
```
=== "CLI"
```console
ruff check --extend-select HYP001
```
It also would _not_ be enabled by selecting the `HYP` category, like so:
=== "pyproject.toml"
@ -79,6 +99,13 @@ It also would _not_ be enabled by selecting the `HYP` category, like so:
extend-select = ["HYP"]
```
=== "CLI"
```console
ruff check --extend-select HYP
```
Similarly, it would _not_ be enabled via the `ALL` selector:
=== "pyproject.toml"
@ -95,7 +122,13 @@ Similarly, it would _not_ be enabled via the `ALL` selector:
select = ["ALL"]
```
However, it would be enabled in any of the above cases if you enabled preview in your configuration file:
=== "CLI"
```console
ruff check --select ALL
```
However, it _would_ be enabled in any of the above cases if you enabled preview mode:
=== "pyproject.toml"
@ -113,7 +146,11 @@ However, it would be enabled in any of the above cases if you enabled preview in
preview = true
```
Or, if you provided the `--preview` CLI flag.
=== "CLI"
```console
ruff check --extend-select HYP --preview
```
To see which rules are currently in preview, visit the [rules reference](rules.md).