Document rule acceptance guidelines by ntBre · Pull Request #27910 · astral-sh/ruff

ntBre · 2026-08-19T22:38:47Z

Summary

This PR includes the contributor-facing documentation for the new categories, as well as updated
rule acceptance guidelines built atop them.

I think we could also update our rule request template based on some of these guidelines, but I'll save that for a follow-up once these are solidified.

Test Plan

Future rule requests

ntBre · 2026-08-19T23:06:06Z

    statements, like imports) or `analyze/expression.rs` (if your rule is based on analyzing
    expressions, like function calls).

 1. Map the violation struct to a rule code in `crates/ruff_linter/src/codes.rs` (e.g., `B011`).


Can/should we drop this requirement yet? 😮

It feels like probably not, but it also seems awkward to have to choose both a category and a linter group. This macro also generates a ton of Rule code that we'll have to generate some other way if we stop requiring this mapping.

I don't think we can today? We can remove it once our rule infrastructure supports it

Yep, this is related to what I mentioned for my plan this week. I'm looking into what it would take to support this, but we definitely can't drop this from the docs yet.

MichaReiser · 2026-08-20T09:50:08Z

-### Example: Adding a new lint rule
+### Proposing a new lint rule
+
+A proposal for a new lint rule in Ruff should include the following components:


These are a lot of requirements for proposing a new rule. I think i'd set this as a bar for a PR, or for a rule to be accepted. But I don't think we should enforce this when users open an issue with a rule idea. Even for an issue, that's probably more than I'd ask for.

I think, for an accepted rule, we should have a proposed name, a category, and a draft of What it does, why this is bad, and maybe an example.

I think I agree with you that it's a lot to ask. We do get a lot of very brief rule requests that linger with needs-decision Awaiting a decision from a maintainer , though. I wasn't thinking that we'd instantly close any requests without all this information, but I think the more information provided, the more seriously we can consider a request.

Maybe the name, category, and other sections you mention are a better sweet spot, though.

What do you think about the proposed diagnostic? I thought that was kind of a fun way to capture a lot about the proposed rule without requiring too much work.

I'd also like to find somewhere else to put all of these optional sections, if we remove them here. I don't think we currently have a canonical list of typical documentation sections. Maybe I could better clarify that all of these requirements should be met by the time a rule is added and note which parts can be deferred for the implementation PR. That would help with the ecosystem circularity too.

I guess we don't want to discourage too many people from opening rule requests, but I kind of don't mind documenting the "ideal" process, assuming that most people won't read or follow it anyway.

I added a note trying to clarify this for now.

I agree with you on needs-decision and I'd love to reduce the number of issues labeled with needs-decision. What if it's more a two-stage process. You can still open issues with very brief descriptions. We take an initial look to decide whether this roughly fits into Ruff and, if so, mark it as needs-design and ask for someone to fill out our template (we can link to this very specific guide). Requests that never make it past needs-design can be closed after , unless we think this is a rule we should add.

What do you think about the proposed diagnostic? I thought that was kind of a fun way to capture a lot about the proposed rule without requiring too much work.

I think it's a very nice idea because it also raises questions around the rule's span and how to convey the problem. But I don't think I'd make it a requirement for a rule to be accepted. It's a nice bonus. It's something that we can also iterate on in the PR.

I added an initial note about a brief issue being okay, mentioning the needs-design step, and further separating out the parts needed for the design proposal and implementation.

MichaReiser · 2026-08-20T10:01:02Z

+almost always a mistake, but in some narrow cases beyond Ruff's understanding, it may be
+intentional, in which case a `noqa` or `ruff: ignore` comment should be used. Such suppression
+comments should essentially never be reasonable for a `correctness` lint but are fine for
+`suspicious` lints.

-At a high level, the steps involved in adding a new lint rule are as follows:
+The final branch of the flow chart deals with stylistic lints, which are again somewhat subjective
+to differentiate between because changes that make code simpler often also make the code faster and
+more idiomatic. Thus, the question prompts you to consider the _primary_ improvement. Rules that
+primarily make code simpler are `complexity` lints, those that primarily make code faster or use
+less memory are `performance` lints, and those that primarily make code more idiomatic are `style`.

-1. Determine a name for the new rule as per our [rule naming convention](#rule-naming-convention)
-    (e.g., `AssertFalse`, as in, "allow `assert False`").
+#### Other guidelines
+
+Following these steps should generally ensure that a rule is a good fit for Ruff. A couple of
+additional things to watch out for are:
+
+- Rules that conflict with other tools, or especially other rules
+
+    Although we have many existing `formatting` rules that overlap and even conflict with our
+    formatter, we are not eager to add more. Similarly, we should avoid rules that mainly support
+    type checker usage, when type checkers themselves emit similar diagnostics. Most clearly, we
+    should avoid rules that overlap or conflict with other lint rules. This often suggests that the
+    existing rule should instead be made configurable to toggle between the two behaviors.
+
+    Checking both the input and output examples from your rule proposal with `ALL` rules selected in


We could link to multiplay here. @AlexWaygood do we have a public link?

multiplay is a public repo! https://github.com/astral-sh/multiplay

multiplay is still not hosted anywhere, so you do have to clone the repo and then run it locally, though

I thought about adding pre-configured Ruff and ty playground links here at least. I'll give that a try since multiplay isn't hosted anywhere.

MichaReiser · 2026-08-20T10:03:06Z

+    libraries, but this niche should be filled by plugins in the near future. Most Ruff rules should
+    apply to Python language features or to functionality from the standard library.


Clippy explicitly is open to widely used third party libraries. I do think this makes sense, similar to ty supporting attrs etc. But I agree, I wouldn't count airflow as one such library because it's very specific. But libraries that are so widely used that you find them in almost every application, having suspicious and correctness rules for those seems valuable to most of our users.

I'd feel more hesitant from adding deprecation rules for third party libraries. That feels like a good use for plugins

I agree with all of that. Does this read as too firm? I tried to make this whole #### Other guidelines section read as general guidance with room for exceptions, but that may not come across clearly enough.

I intended it to be somewhat firm but may have gone too far.

It does sound to me that rule requests for third-party libraries would always be reject. Our stance here might also change once we support plugins

I've tried to soften this and also removed the mention of plugins for now.

astral-sh-bot · 2026-08-20T18:56:19Z

`ruff-ecosystem` results

Linter (stable)

✅ ecosystem check detected no linter changes.

Linter (preview)

✅ ecosystem check detected no linter changes.

Formatter (stable)

✅ ecosystem check detected no format changes.

Formatter (preview)

✅ ecosystem check detected no format changes.

jelle-openai · 2026-08-21T16:35:47Z

+
+#### Other guidelines
+
+Following these steps should generally ensure that a rule is a good fit for Ruff. A couple of


I actually don't see much in here that explains when Ruff would accept a rule, it's much more about the mechanics of how to add one. What criteria would you (the Ruff maintainers) use to decide whether or not to accept a rule? This guideline offers some special cases but not a general set of principles on which to base the decision.

I can see what you mean, but I guess my thinking was if you've followed these steps and come up with:

a good name

a suitable category

convincing "what it does" and especially "why is this bad" docs

and not violated any of these special cases (or made a case for why your rule is an exception), then we'd accept the rule. I don't think the goal is to set a super high bar, just standardize some of the things we look for and make sure we have enough information for an acceptance decision. That's part of why I didn't actually end up using "Rule Acceptance Guidelines" directly in the docs.

One of the goals of the new categories is actually to make it easier to add rules without having to worry so much about their linter codes.

codspeed · 2026-08-21T17:17:51Z

Merging this PR will not alter performance

✅ 60 untouched benchmarks
⏩ 150 skipped benchmarks¹

_{Comparing brent/rule-acceptance-guidelines (e20dedb) with brent/category-docs (0f847a5)²}

150 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩
No successful run was found on brent/category-docs (5518fd2) during the generation of this report, so b8fc8be was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

ntBre · 2026-08-25T18:52:54Z

+Note that "useless" in the context of a `correctness` rule should be indicative of a mistake. For
+example, `useless-exception-statement` (`PLW0133`) flags exceptions that are constructed and never
+raised, suggesting that the user forgot to raise or otherwise use them. In contrast, code that is
+merely unnecessary but still working as intended may be a better fit for `complexity`, such as
+`useless-try-except` (`TRY203`). As described above, if the code is probably not intentional but may
+be in certain cases, `suspicious` can also be a good fit.


Added this note about "useless" vs "unnecessary" in light of our discussions.

Thanks. I like this. I wonder if we should also mention style.

Summary -- This PR includes the contributor-facing documentation for the new categories, as well as updated rule acceptance guidelines built atop them. Test Plan -- Future rule requests and manual testing of the rule request template in my personal Ruff fork

Co-authored-by: Micha Reiser <micha@reiser.io>

Summary -- This PR includes the contributor-facing documentation for the new categories, as well as updated rule acceptance guidelines built atop them. I think we could also update our rule request template based on some of these guidelines, but I'll save that for a follow-up once these are solidified. Test Plan -- Future rule requests --------- Co-authored-by: Micha Reiser <micha@reiser.io>

ntBre added the documentation Improvements or additions to public-facing documentation label Aug 19, 2026

ntBre commented Aug 19, 2026

View reviewed changes