From 7ac9e0252e3c278078e19a7053671fdc845986af Mon Sep 17 00:00:00 2001 From: konsti Date: Mon, 3 Jul 2023 11:22:19 +0200 Subject: [PATCH] Document Checking formatter stability and panics (#5415) This adds the documentation, but ideally we should add the CI first --- crates/ruff_python_formatter/README.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/crates/ruff_python_formatter/README.md b/crates/ruff_python_formatter/README.md index 0dde0b475f2d4..b115eb1754a73 100644 --- a/crates/ruff_python_formatter/README.md +++ b/crates/ruff_python_formatter/README.md @@ -241,6 +241,29 @@ 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 + +There are tree 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` + +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 +``` + +It is also possible large number of repositories using ruff. This dataset is large (~60GB), so we +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 +``` + ## The orphan rules and trait structure For the formatter, we would like to implement `Format` from the rust_formatter crate for all AST