Better documentation of unsafe fixes

[hauntsaninja]

It would be nice if it was easier to figure out what checks have unsafe fixes, e.g. maybe there could be a different icon next to the rules in https://docs.astral.sh/ruff/rules/

It would also be nice if the per-rule documentation also mentioned why the fix is unsafe. E.g. for https://docs.astral.sh/ruff/rules/unnecessary-comprehension/ I'm left guessing, is it because ruff will apply the fix even when dict is bound to something else (edit: maybe because cases where we unpack we now lose errors)?

(For some user context: on a lot of our code, we only run ruff for autofixes and do not report errors for unfixable lints. Autofixing is a killer feature)

[charliermarsh]

Yeah that's a nice idea. We've started doing this in some places via a "Known problems" section. I'll try to get the remaining rules covered next week.

(If helpful, you can also set unsafe-fixes = true in your configuration file to get the same behavior as before we shipped the applicability settings -- but I assume you're asking because you want to know which rules you should be fixing vs. not :))

[Avasam]

There's some overlap in the ideas from my comment in #8075 (comment) so I'll copy here as well:

On the rule page itself, I think you could have:
"Fix is always available" / "Fix is sometimes available" / (no fix available)
and separately mention that "Some fixes are marked unsafe by default"

I don't think it's necessary to mention that "All fixes are unsafe". But at a user I wouldn't mind being a touch more exact. As long as it is show that I need to run --unsafe-fixes to get all the available fixes.

---

As for the "all rules" page.
You could differentiate between "sometimes autofixable" and "always autofixable" with 🔨 or 🔧, it's visually just 🛠️ but with a tool missing. I personally quite like that.

As fox fix safety, I'm less certain of the best way to display that / convey the information concisely. I think that adding a column should be fine.
The first thing that comes to mind is ⚠️, but it looks out of place/scary even when grayed out:

Other suggestions may include ⁉, 🚦, or just annotating the autofix with *, or even get fancy with it with a set-width column (or a 0-width element translated to the right position):

[zanieb]

Please let us know if there's a rule with an unsafe fix that is not explained in the documentation, we can start tracking adding documentation at least.

[hauntsaninja]

Rule with unsafe fix that caused me to open this issue was C416. I'll post on here as I notice others :-)

[sh-at-cs]

Why the fix is unsafe is not explained for UP007, as mentioned in #8868.

[charliermarsh]

(Adding docs for those rules now.)

[charliermarsh]

Done in #8918.

[hauntsaninja]

A few more unsafe fixes that could use docs:

• UP028
• PERF102
• PT014
• PYI025
• PLR6201

[charliermarsh]

I think UP028 might be safe except in very rare circumstances. I'm trying to come up with an example in which the modification could lead to a breaking change.