Improvements to rule docs: versions and fix safety

[inoa-jboliveira]

Hi everyone, I wanted to suggest two improvements to Ruff rules documentation. I find myself using this page almost daily because we are refactoring a large (>1MLOC) project and we are adding rules bit by bit.

1. I would like to know when a rule was made available, became stable, had changes to it (e.g. v0.1.2 experimental, v0.2.0 became stable, v0.2.4 behavior changed when foo is greater than bar) and also when it was deprecated and/or removed.
   This one is quite important because we tend to update ruff very often here.

2. Have the docs explain why a fix is considered unsafe vs when it is safe.
   I believe safety is defined when there are no behavior changed as opposed to unsafe fix which would perform a different but similar operation. Lets say if bytecode changes between two source codes, behavior changes and the rule is deemed unsafe. Right?

   In this case, it would be extremely useful if the rule said how the behavior is changing. E.g. rule TID252 changes relative imports into absolute, but sometimes the top level name clashes with another package and the final imported package may be different than the one intended.

   That allows the developer to know what to look for when checking a fixed version of the code.

Bonus:

3. Show different icons for when the fix is safe, unsafe or may be either one depending on the code (e.g. blue, red or yellow hammer and wrench icon)

   https://docs.astral.sh/ruff/rules

[zanieb]

👋 Welcome

1. This would be nice, but we don't have any tooling for it yet. Feel free to open an issue.

2. See Better documentation of unsafe fixes #8482 — we've attempted to document all cases of unsafe fixes.

3. Unfortunately this isn't straight-forward because the rule can offer multiple fixes, some safe some unsafe, and we don't define these until runtime. We could add some sort of enum that needs to be manually updated to reflect the possible safety levels. Might make sense though I worry it could become outdated.

[inoa-jboliveira]

Sure, thank you. I opened #11369 for item 1

Regarding item 2, I think many rules don't show why they may be unsafe, specifically new ones.

[zanieb]

Feel free to open issues for any you find missing documentation. We try to enforce this when new rules are added but we miss some.