language-servers/ruff
1
0
Fork 0
mirror of https://github.com/astral-sh/ruff.git synced 2025-08-03 18:28:56 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

Add format-dev contributor docs (#5594)

Browse source 
## Summary

This adds markdown-level docs for #5492

## Test Plan

n/a

---------

Co-authored-by: Micha Reiser <micha@reiser.io>
This commit is contained in:
konsti 2023-07-07 18:52:13 +02:00 • committed by GitHub
parent bb7303f867
commit 0f9d7283e7
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 17 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

22
crates/ruff_python_formatter/README.md
View file

@ -241,18 +241,30 @@ The origin of Ruff's formatter is the [Rome formatter](https://github.com/rome/t
e.g. the ruff_formatter crate is forked from the [rome_formatter crate](https://github.com/rome/tools/tree/main/crates/rome_formatter).
The Rome repository can be a helpful reference when implementing something in the Ruff formatter
### Checking formatter stability and panics
### Checking entire projects
There are tree common problems with the formatter: The second formatting pass looks different than
It's possible to format an entire project:
```shell
cargo run --bin ruff_dev -- format-dev --write my_project
```
This will format all files that `ruff check` would lint and computes the
[Jaccard index](https://en.wikipedia.org/wiki/Jaccard_index), a measure for how close the original
and formatted versions are. The Jaccard index is 1 if there were no changes at all, while 0 means
every line was changed. If you run this on a black formatted projects, this tells you how similar
the ruff formatter is to black for the given project, with our goal being as close to 1 as possible.
There are three common problems with the formatter: The second formatting pass looks different than
the first (formatter instability or lack of idempotency), we print invalid syntax (e.g. missing
parentheses around multiline expressions) and panics (mostly in debug assertions). We test for all
of these using the `check-formatter-stability` subcommand in `ruff_dev`
of these using the `--stability-check` option in the `format-dev` subcommand:
The easiest is to check CPython:
```shell
git clone --branch 3.10 https://github.com/python/cpython.git crates/ruff/resources/test/cpython
cargo run --bin ruff_dev -- check-formatter-stability crates/ruff/resources/test/cpython
cargo run --bin ruff_dev -- format-dev --stability-check crates/ruff/resources/test/cpython
```
It is also possible large number of repositories using ruff. This dataset is large (~60GB), so we
@ -261,7 +273,7 @@ only do this occasionally:
```shell
curl https://raw.githubusercontent.com/akx/ruff-usage-aggregate/master/data/known-github-tomls.jsonl > github_search.jsonl
python scripts/check_ecosystem.py --checkouts target/checkouts --projects github_search.jsonl -v $(which true) $(which true)
cargo run --bin ruff_dev -- check-formatter-stability --multi-project target/checkouts
cargo run --bin ruff_dev -- format-dev --stability-check --multi-project target/checkouts
```
## The orphan rules and trait structure