feat: additional rule metadata for deprecations #124

DMartens · 2024-09-12T21:50:03Z

Summary

This is a continuation of #116 by @bmish to specify additional properties for rule deprecations.
The main changes are:

move all properties under meta.deprecated and deprecate meta.replacedBy
"shorthands" for properties
additional properties: kind, deprecatedSince, availableUntil
more open questions

Related Issues

Change Request: Support additional rule metadata for deprecations eslint#18061

mdjermanovic · 2024-09-17T08:27:31Z

designs/2024-deprecated-rule-metadata/README.md

+type ReplacementKind =
+ 'moved' | // The rule has moved to another plugin if plugin is set, otherwise the rule is renamed in the same plugin
+ 'merged' | // The rule merged with another rule
+ 'option' // The current rule behavior is available as an option in the replacement rule


I think ReplacedByInfo.kind isn't necessary as this info and more context can be provided as part of the ReplacedByInfo.info (or ReplacedByInfo.info.message) text.

The idea behind this property was:

for documentation generators: able to provide a default "message" without having to specify the same message for multiple rules (e.g. the rule was renamed from "foo" to "bar")

a possible config migration tool: suggest changes without relying on a specific format in info.message (e.g. rename the rule in the config)

I'm also not sure of the value here. A single word just doesn't given enough context. I also fear this would become a maintenance issue as we'll end finding other reasons rules were deprecated and need to update this list with more unclear terms.

mdjermanovic · 2024-09-17T08:46:50Z

designs/2024-deprecated-rule-metadata/README.md

+ deprecatedSince?: Version // Helps users gauge when to migrate and useful for documentation
+ availableUntil?: Version | null // The estimated version when the rule is removed (probably the next major version). null means the rule is "frozen" (will be available but will not be changed)


Shouldn't these two properties rather be on DeprecateInfo, as they don't seem related to particular replacements but the deprecation itself?

Yes, they should be.

mdjermanovic · 2024-09-17T08:57:58Z

designs/2024-deprecated-rule-metadata/README.md

+### Shorthand
+The shorthand for the properties `plugin`, `rule` and `info` is just a string representing either the `name`/`message` or the `url` based on its content.
+If it starts with a protocol (e.g. `https://`) the property should be interpreted as if only the `url` property is set, otherwise it should be interpreted as `name`/`message` property.
+This shorthand also applies for the existing `meta.deprecated` which then applies for the `meta.deprecated.info` properties.
+Some examples:
+```js
+{ meta: { deprecated: { plugin: 'https://eslint.style' } } } // <=> { meta: { deprecated: { plugin: { url: 'https://eslint.style' } } } }
+{ meta: { deprecated: { plugin: '@eslint-stylistic/js' } } } // <=> { meta: { deprecated: { plugin: { name: '@eslint-stylistic/js' } } } }
+{ meta: { deprecated: 'https://eslint.style/guide/migration' } // <=> { meta: { deprecated: { info: { url: 'https://eslint.style/guide/migration' } } } }
+```


In my opinion, this is an unnecessary complexity that tooling would need to support. I'd be in favor of dropping shorthands to simplify this. Deprecations don't happen often, and it doesn't take much effort to write an object with a name or url property instead of a string.

The primary motiviation for this were comments in the initial proposal how an empty object should be interpreted. With the shorthands, we can make all properties required instead of at least one property.

Agree with @mdjermanovic on this.

mdjermanovic · 2024-09-17T09:11:41Z

designs/2024-deprecated-rule-metadata/README.md

+3. Should the exact regular expression for the shorthand which decides whether it is a description or URL be specified?
+4. Should the shorthand also be applied for the string form of the `meta.deprecated` property?


I'd prefer dropping shorthands, so we wouldn't have these questions.

mdjermanovic · 2024-09-17T09:28:24Z

designs/2024-deprecated-rule-metadata/README.md

+5. Which "extension points" (rules, processors, configurations, parsers, formatters) shold be supported?
+6. Should the `rule` key be dependent on the "extension point" (e.g. `processor` for processors) or renamed (e.g. ``) so that it is the same property name for all?


I think the scope of this RFC is just rules deprecations. But if we are already anticipating that other extension points (processors, configurations, parsers, formatters) will have deprecation info, with the same shape, then a more generic name like replacement might have sense, so that it's the same property name for all.

I do not know of examples for other extension points being deprecated but especially with the introduction of language plugins, I can see some processors being deprecated (e.g. eslint-plugin-markdown).

…bject

nzakas · 2024-09-18T14:42:37Z

designs/2024-deprecated-rule-metadata/README.md

+};
+
+/* At least one property is required */
+type DeprecateInfo = {


Suggested change

type DeprecateInfo = {

type DeprecatedInfo = {

nzakas · 2024-09-18T14:44:30Z

designs/2024-deprecated-rule-metadata/README.md

+ kind?: ReplacementKind // Defaults to "moved" if missing
+}
+
+type Message = {


I'm not sure this type is necessary. I'd rather just move message and url to DeprecatedInfo and ReplacedByInfo. Remove one level of objects.

nzakas · 2024-09-18T14:48:27Z

designs/2024-deprecated-rule-metadata/README.md

+type ReplacementKind =
+ 'moved' | // The rule has moved to another plugin if plugin is set, otherwise the rule is renamed in the same plugin
+ 'merged' | // The rule merged with another rule
+ 'option' // The current rule behavior is available as an option in the replacement rule


I'm also not sure of the value here. A single word just doesn't given enough context. I also fear this would become a maintenance issue as we'll end finding other reasons rules were deprecated and need to update this list with more unclear terms.

nzakas · 2024-09-18T14:49:19Z

designs/2024-deprecated-rule-metadata/README.md

+ rule: 'https://eslint.style/rules/js/semi',
+ },


Syntax error

nzakas · 2024-09-18T14:50:03Z

designs/2024-deprecated-rule-metadata/README.md

+ message: 'Stylistic rules are being moved out of ESLint core.',
+ url: 'https://eslint.org/blog/2023/10/deprecating-formatting-rules/',


message and url aren't listed as members above (although, I do like this better. See my earlier comments.)

nzakas · 2024-09-18T14:51:37Z

designs/2024-deprecated-rule-metadata/README.md

+### Shorthand
+The shorthand for the properties `plugin`, `rule` and `info` is just a string representing either the `name`/`message` or the `url` based on its content.
+If it starts with a protocol (e.g. `https://`) the property should be interpreted as if only the `url` property is set, otherwise it should be interpreted as `name`/`message` property.
+This shorthand also applies for the existing `meta.deprecated` which then applies for the `meta.deprecated.info` properties.
+Some examples:
+```js
+{ meta: { deprecated: { plugin: 'https://eslint.style' } } } // <=> { meta: { deprecated: { plugin: { url: 'https://eslint.style' } } } }
+{ meta: { deprecated: { plugin: '@eslint-stylistic/js' } } } // <=> { meta: { deprecated: { plugin: { name: '@eslint-stylistic/js' } } } }
+{ meta: { deprecated: 'https://eslint.style/guide/migration' } // <=> { meta: { deprecated: { info: { url: 'https://eslint.style/guide/migration' } } } }
+```


Agree with @mdjermanovic on this.

nzakas · 2024-09-18T14:52:36Z

designs/2024-deprecated-rule-metadata/README.md

+-->
+
+1. Is there additional deprecation information we'd like to represent? Note that additional information can always be added later, but it's good to consider any possible needs now.
+2. Should `meta.deprecated.plugin.id` accommodate different package registries (e.g. [jsr](https://jsr.io/) with `jsr:eslint-plugin-example`)


Suggested change

2. Should `meta.deprecated.plugin.id` accommodate different package registries (e.g. [jsr](https://jsr.io/) with `jsr:eslint-plugin-example`)

2. Should `meta.deprecated.plugin.name` accommodate different package registries (e.g. [jsr](https://jsr.io/) with `jsr:eslint-plugin-example`)

In general, I don't think we should worry about package registries. People should include a URL to the package wherever its published if this is a concern.

feat: additional rule metadata for deprecations

bc0ed7c

eslint-github-bot bot added the feature label Sep 12, 2024

DMartens mentioned this pull request Sep 12, 2024

feat: support additional metadata for rule deprecations #116

Closed

nzakas added the Initial Commenting This RFC is in the initial feedback stage label Sep 13, 2024

mdjermanovic reviewed Sep 17, 2024

View reviewed changes

fix: move deprecatedSince and availableUntil to the root deprecated o…

83f99ac

…bject

nzakas reviewed Sep 18, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: additional rule metadata for deprecations #124

feat: additional rule metadata for deprecations #124

DMartens commented Sep 12, 2024

mdjermanovic Sep 17, 2024

DMartens Sep 18, 2024

nzakas Sep 18, 2024

mdjermanovic Sep 17, 2024

DMartens Sep 18, 2024

mdjermanovic Sep 17, 2024

DMartens Sep 18, 2024

nzakas Sep 18, 2024

mdjermanovic Sep 17, 2024

mdjermanovic Sep 17, 2024

DMartens Sep 18, 2024

nzakas Sep 18, 2024

nzakas Sep 18, 2024

nzakas Sep 18, 2024

nzakas Sep 18, 2024

nzakas Sep 18, 2024

nzakas Sep 18, 2024

nzakas Sep 18, 2024

nzakas Sep 18, 2024

		deprecatedSince?: Version // Helps users gauge when to migrate and useful for documentation
		availableUntil?: Version \| null // The estimated version when the rule is removed (probably the next major version). null means the rule is "frozen" (will be available but will not be changed)

		3. Should the exact regular expression for the shorthand which decides whether it is a description or URL be specified?
		4. Should the shorthand also be applied for the string form of the `meta.deprecated` property?

		5. Which "extension points" (rules, processors, configurations, parsers, formatters) shold be supported?
		6. Should the `rule` key be dependent on the "extension point" (e.g. `processor` for processors) or renamed (e.g. ``) so that it is the same property name for all?

		message: 'Stylistic rules are being moved out of ESLint core.',
		url: 'https://eslint.org/blog/2023/10/deprecating-formatting-rules/',

	2. Should `meta.deprecated.plugin.id` accommodate different package registries (e.g. [jsr](https://jsr.io/) with `jsr:eslint-plugin-example`)
	2. Should `meta.deprecated.plugin.name` accommodate different package registries (e.g. [jsr](https://jsr.io/) with `jsr:eslint-plugin-example`)

feat: additional rule metadata for deprecations #124

Are you sure you want to change the base?

feat: additional rule metadata for deprecations #124

Conversation

DMartens commented Sep 12, 2024

Summary

Related Issues

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment