Respect `#(deprecated)` attribute in configuration options #8035

MichaReiser · 2023-10-18T03:13:32Z

Summary

This PR extends the OptionsMetadata derive macro to respect the deprecated attribute.

Adding the deprecated attribute to an option does:

Mark the option as deprecated in the json schema (handled by schemars)
Adds a deprecated message to the documentation
Shows a (deprecated) label when listing the configurations with ruff config
Shows the deprecation message when showing an option with ruff config <name>

deprecated is not yet supported for groups.

Test Plan

 cargo run --bin ruff -q -- config extend-ignore
A list of rule codes or prefixes to ignore, in addition to those
specified by `ignore`.

Default value: []
Type: list[RuleSelector]
Deprecated: This option has been **deprecated** in favor of `ignore` since its usage is now interchangeable with `ignore`.
Example usage:
..

cargo run --bin ruff -q -- config 
cache-dir
extend
...
extend-ignore (deprecated)

MichaReiser · 2023-10-18T03:13:45Z

Current dependencies on/for this PR:

main
- PR Add [format|lint].exclude options #8000
  - PR Add lint.preview #8002
    - PR Document lint.preview and format.preview #8032
    - PR Respect tab-size setting in formatter #8006
      - PR Respect #(deprecated) attribute in configuration options #8035 👈
        
        PR Rename *-length options to -width #8010
        
        PR Rename tab-size to indent-width #8082
        
        PR Warn about incompatible formatter options #8088
        
        PR New pycodestyle.max-line-length option #8039
      - PR Options: Support #[serde(alias = name)] #8031

This comment was auto-generated by Graphite.

MichaReiser · 2023-10-18T03:45:48Z

crates/ruff_macros/src/config.rs

@@ -212,39 +233,109 @@ struct FieldAttributes {
    example: String,
 }

-impl Parse for FieldAttributes {
-    fn parse(input: ParseStream) -> syn::Result<Self> {
-        let default = _parse_key_value(input, "default")?;


The old logic relied on the specific order. The new logic allows arbitrary ordering and is in line with that serde and other crates use for parsing attribute fields.

MichaReiser · 2023-10-18T03:48:13Z

ruff.schema.json

@@ -1662,6 +1695,17 @@
            "$ref": "#/definitions/RuleSelector"
          }
        },
+        "extend-unfixable": {


We shouldn't remove deprecated options from the schema to avoid existing configurations failing the schema validation.

charliermarsh

When we rename an option, will we leave the deprecated variant and mark it as deprecated? I assume both will then show up in the documentation.

crates/ruff_dev/src/generate_options.rs

github-actions · 2023-10-19T00:05:03Z

PR Check Results

Ecosystem

✅ ecosystem check detected no changes.

MichaReiser · 2023-10-19T00:05:24Z

When we rename an option, will we leave the deprecated variant and mark it as deprecated? I assume both will then show up in the documentation.

Yes, marking an option as deprecated has the result that both, the new and the deprecated, options show up in the documentation. We can customize the layout for deprecated options if we want.

I considered alternatives for the special case of renaming options but they all require more tooling support which I'm not sure is worth building. What I want is that:

Both the new and deprecated options are in the json schema. The deprecated option must be marked as deprecated in the schema.
Ideally: The deprecated name is listed next to the new configuration name.

The challenge is that we need two fields to know if the user used the deprecated field (we could create a custom deserializer and emit the warning in the deserializer but it will be challenging to ever return this warning as a diagnostic in the future). Also, schemars needs two fields to have both show up in the schema.

We could remove the option attribute from the deprecated option and add a deprecated_alias field to the option attribute. But it felt like too much complexity for the few deprecated options that we have today.

henryiii · 2023-10-19T21:31:15Z

Curious to see how SchemaStore (and other validators, like fastjsonschema) handle this - might need to be added to the ignored keyword list in their internal validator (which is easy to do per schema). Technically, it was added in draft 2019, which pretty much nothing seems to officially support. But like other features, I don't think extra keywords are disallowed, and validators may start picking up on this (besides schemas, I know there's discussion on making jsonschema in Python support it).

(This is my favorite 2019 feature, though, and I'd love to see it added everywhere)

zanieb · 2023-10-19T22:09:30Z

Thanks for the notes! We'll see at SchemaStore/schemastore#3332

MichaReiser · 2023-10-19T23:05:56Z

Interesting, I assumed that this is well supported, considering that 2020-12 is the most recent json schema specification

henryiii · 2023-10-19T23:08:21Z

It would be nice if the description in JSONSchema would include the deprecation reason. I wasn’t aware that extend-ignore was deprecated and the schema didn’t say why.

henryiii · 2023-10-19T23:11:19Z

Most tools seem to have frozen at draft 7. Fastjsonschema (used by validate-pyproject) requires 7. Even schemastore requires 7: https://github.com/SchemaStore/schemastore/blob/master/CONTRIBUTING.md#best-practices

MichaReiser · 2023-10-19T23:36:33Z

It would be nice if the description in JSONSchema would include the deprecation reason. I wasn’t aware that extend-ignore was deprecated and the schema didn’t say why.

Yeah. I haven't figured out a good (technical) solution to this yet which doesn't require us to re-implement schemar's derive macro other than copying the deprecation message into the description. It's a pity that the json schema deprecated field is a boolean and doesn't allow specifying a message

This was referenced Oct 18, 2023

Add [format|lint].exclude options #8000

Merged

Add lint.preview #8002

Merged

Respect tab-size setting in formatter #8006

Merged

Document lint.preview and format.preview #8032

Merged

Rename *-length options to -width #8010

Closed

MichaReiser mentioned this pull request Oct 18, 2023

Options: Support #[serde(alias = name)] #8031

Closed

MichaReiser added the configuration Related to settings and configuration label Oct 18, 2023

MichaReiser force-pushed the options-deprecated branch from 0e630f3 to bdcf7c1 Compare October 18, 2023 03:44

MichaReiser added the documentation Improvements or additions to documentation label Oct 18, 2023

MichaReiser commented Oct 18, 2023

View reviewed changes

MichaReiser changed the title ~~Respect deprecated attribute in configuration options~~ Respect #(deprecated) attribute in configuration options Oct 18, 2023

MichaReiser marked this pull request as ready for review October 18, 2023 06:17

MichaReiser requested review from charliermarsh and zanieb October 18, 2023 06:17

MichaReiser force-pushed the formatter-respect-tab-size branch from a583805 to f1b00ca Compare October 18, 2023 06:30

MichaReiser force-pushed the options-deprecated branch from bdcf7c1 to f2ac348 Compare October 18, 2023 06:30

MichaReiser mentioned this pull request Oct 18, 2023

New pycodestyle.max-line-length option #8039

Merged

charliermarsh approved these changes Oct 18, 2023

View reviewed changes

crates/ruff_dev/src/generate_options.rs Outdated Show resolved Hide resolved

Base automatically changed from formatter-respect-tab-size to main October 18, 2023 23:48

MichaReiser force-pushed the options-deprecated branch from f2ac348 to 03e903d Compare October 18, 2023 23:49

MichaReiser force-pushed the options-deprecated branch from 03e903d to d601bfd Compare October 19, 2023 00:31

Respect deprecated attribute in configuration options

f5ddc5a

MichaReiser force-pushed the options-deprecated branch from d601bfd to f5ddc5a Compare October 19, 2023 00:58

MichaReiser enabled auto-merge (squash) October 19, 2023 00:59

MichaReiser merged commit a85ed30 into main Oct 19, 2023
15 checks passed

MichaReiser deleted the options-deprecated branch October 19, 2023 01:07

p-linnane mentioned this pull request Oct 19, 2023

ruff 0.1.1 Homebrew/homebrew-core#151871

Merged

This was referenced Oct 20, 2023

Rename tab-size to indent-width #8082

Merged

Warn about incompatible formatter options #8088

Merged

henryiii mentioned this pull request Oct 20, 2023

feat: check for deprecated Ruff codes scientific-python/cookie#297

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Respect `#(deprecated)` attribute in configuration options #8035

Respect `#(deprecated)` attribute in configuration options #8035

MichaReiser commented Oct 18, 2023 •

edited

MichaReiser commented Oct 18, 2023 •

edited

MichaReiser Oct 18, 2023

MichaReiser Oct 18, 2023

charliermarsh left a comment

github-actions bot commented Oct 19, 2023 •

edited

MichaReiser commented Oct 19, 2023

henryiii commented Oct 19, 2023

zanieb commented Oct 19, 2023

MichaReiser commented Oct 19, 2023

henryiii commented Oct 19, 2023 •

edited

henryiii commented Oct 19, 2023 •

edited

MichaReiser commented Oct 19, 2023 •

edited

Respect #(deprecated) attribute in configuration options #8035

Respect #(deprecated) attribute in configuration options #8035

Conversation

MichaReiser commented Oct 18, 2023 • edited

Summary

Test Plan

MichaReiser commented Oct 18, 2023 • edited

MichaReiser Oct 18, 2023

Choose a reason for hiding this comment

MichaReiser Oct 18, 2023

Choose a reason for hiding this comment

charliermarsh left a comment

Choose a reason for hiding this comment

github-actions bot commented Oct 19, 2023 • edited

PR Check Results

Ecosystem

MichaReiser commented Oct 19, 2023

henryiii commented Oct 19, 2023

zanieb commented Oct 19, 2023

MichaReiser commented Oct 19, 2023

henryiii commented Oct 19, 2023 • edited

henryiii commented Oct 19, 2023 • edited

MichaReiser commented Oct 19, 2023 • edited

Respect `#(deprecated)` attribute in configuration options #8035

Respect `#(deprecated)` attribute in configuration options #8035

MichaReiser commented Oct 18, 2023 •

edited

MichaReiser commented Oct 18, 2023 •

edited

github-actions bot commented Oct 19, 2023 •

edited

henryiii commented Oct 19, 2023 •

edited

henryiii commented Oct 19, 2023 •

edited

MichaReiser commented Oct 19, 2023 •

edited