diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 29c9fd8cf6..e0164ee8a9 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -56,9 +56,9 @@ prior to merging. There are four phases to adding a new lint rule: -1. Define the violation in `src/violations.rs` (e.g., `ModuleImportNotAtTopOfFile`). -2. Map the violation to a code in `src/registry.rs` (e.g., `E402`). -3. Define the _logic_ for triggering the violation in `src/checkers/ast.rs` (for AST-based checks), +1. Define the violation struct in `src/violations.rs` (e.g., `ModuleImportNotAtTopOfFile`). +2. Map the violation struct to a rule code in `src/registry.rs` (e.g., `E402`). +3. Define the logic for triggering the violation in `src/checkers/ast.rs` (for AST-based checks), `src/checkers/tokens.rs` (for token-based checks), or `src/checkers/lines.rs` (for text-based checks). 4. Add a test fixture. 5. Update the generated files (documentation and generated code). @@ -74,15 +74,16 @@ collecting diagnostics as it goes. If you need to inspect the AST, you can run `cargo +nightly dev print-ast` with a Python file. Grep for the `Check::new` invocations to understand how other, similar rules are implemented. -To add a test fixture, create a file under `resources/test/fixtures/[plugin-name]`, named to match -the code you defined earlier (e.g., `E402.py`). This file should contain a variety of -violations and non-violations designed to evaluate and demonstrate the behavior of your lint rule. +To add a test fixture, create a file under `resources/test/fixtures/[origin]`, named to match +the code you defined earlier (e.g., `resources/test/fixtures/pycodestyle/E402.py`). This file should +contain a variety of violations and non-violations designed to evaluate and demonstrate the behavior +of your lint rule. Run `cargo +nightly dev generate-all` to generate the code for your new fixture. Then run Ruff locally with (e.g.) `cargo run resources/test/fixtures/pycodestyle/E402.py --no-cache --select E402`. Once you're satisfied with the output, codify the behavior as a snapshot test by adding a new -`test_case` macro in the relevant `src/[plugin-name]/mod.rs` file. Then, run `cargo test --all`. +`test_case` macro in the relevant `src/[origin]/mod.rs` file. Then, run `cargo test --all`. Your test will fail, but you'll be prompted to follow-up with `cargo insta review`. Accept the generated snapshot, then commit the snapshot file alongside the rest of your changes. diff --git a/README.md b/README.md index 97e988c58d..706bb270da 100644 --- a/README.md +++ b/README.md @@ -164,9 +164,9 @@ pacman -S ruff To run Ruff, try any of the following: ```shell -ruff path/to/code/to/check.py # Run Ruff over `check.py` -ruff path/to/code/ # Run Ruff over all files in `/path/to/code` (and any subdirectories) -ruff path/to/code/*.py # Run Ruff over all `.py` files in `/path/to/code` +ruff path/to/code/to/lint.py # Run Ruff over `lint.py` +ruff path/to/code/ # Run Ruff over all files in `/path/to/code` (and any subdirectories) +ruff path/to/code/*.py # Run Ruff over all `.py` files in `/path/to/code` ``` You can run Ruff in `--watch` mode to automatically re-run on-change: @@ -237,9 +237,9 @@ target-version = "py310" max-complexity = 10 ``` -As an example, the following would configure Ruff to: (1) avoid checking for line-length -violations (`E501`); (2) never remove unused imports (`F401`); and (3) ignore import-at-top-of-file -errors (`E402`) in `__init__.py` files: +As an example, the following would configure Ruff to: (1) avoid enforcing line-length violations +(`E501`); (2) never remove unused imports (`F401`); and (3) ignore import-at-top-of-file violations +(`E402`) in `__init__.py` files: ```toml [tool.ruff] @@ -269,16 +269,16 @@ select = ["E", "F", "Q"] docstring-quotes = "double" ``` -Ruff mirrors Flake8's error code system, in which each error code consists of a one-to-three letter -prefix, followed by three digits (e.g., `F401`). The prefix indicates that "source" of the error -code (e.g., `F` for Pyflakes, `E` for `pycodestyle`, `ANN` for `flake8-annotations`). The set of -enabled errors is determined by the `select` and `ignore` options, which support both the full -error code (e.g., `F401`) and the prefix (e.g., `F`). +Ruff mirrors Flake8's rule code system, in which each rule code consists of a one-to-three letter +prefix, followed by three digits (e.g., `F401`). The prefix indicates that "source" of the rule +(e.g., `F` for Pyflakes, `E` for `pycodestyle`, `ANN` for `flake8-annotations`). The set of enabled +rules is determined by the `select` and `ignore` options, which support both the full code (e.g., +`F401`) and the prefix (e.g., `F`). -As a special-case, Ruff also supports the `ALL` error code, which enables all error codes. Note that -some of the `pydocstyle` error codes are conflicting (e.g., `D203` and `D211`) as they represent -alternative docstring formats. Enabling `ALL` without further configuration may result in suboptimal -behavior, especially for the `pydocstyle` plugin. +As a special-case, Ruff also supports the `ALL` code, which enables all rules. Note that some of the +`pydocstyle` rules conflict (e.g., `D203` and `D211`) as they represent alternative docstring +formats. Enabling `ALL` without further configuration may result in suboptimal behavior, especially +for the `pydocstyle` plugin. As an alternative to `pyproject.toml`, Ruff will also respect a `ruff.toml` file, which implements an equivalent schema (though the `[tool.ruff]` hierarchy can be omitted). For example, the @@ -326,17 +326,17 @@ Options: -v, --verbose Enable verbose logging -q, --quiet - Only log errors + Print lint violations, but nothing else -s, --silent - Disable all logging (but still exit with status code "1" upon detecting errors) + Disable all logging (but still exit with status code "1" upon detecting lint violations) -e, --exit-zero - Exit with status code "0", even upon detecting errors + Exit with status code "0", even upon detecting lint violations -w, --watch Run in watch mode by re-running whenever files change --fix - Attempt to automatically fix lint errors + Attempt to automatically fix lint violations --fix-only - Fix any fixable lint errors, but don't report on leftover violations. Implies `--fix` + Fix any fixable lint violations, but don't report on leftover violations. Implies `--fix` --diff Avoid writing any fixed files back; instead, output a diff for each changed file to stdout -n, --no-cache @@ -346,23 +346,23 @@ Options: --select