-
-
Notifications
You must be signed in to change notification settings - Fork 4.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Change Request: Standardize documentation properties (e.g. allow configs to export description) #17842
Comments
I was trying to add a Error: Unexpected key "meta" found.
at ObjectSchema.validate (/Users/weiran/repo/github/eslint-plugin-node/node_modules/@humanwhocodes/object-schema/src/object-schema.js:270:23)
at /Users/weiran/repo/github/eslint-plugin-node/node_modules/@humanwhocodes/object-schema/src/object-schema.js:239:18
at Array.reduce (<anonymous>)
at ObjectSchema.merge (/Users/weiran/repo/github/eslint-plugin-node/node_modules/@humanwhocodes/object-schema/src/object-schema.js:237:24)
at /Users/weiran/repo/github/eslint-plugin-node/node_modules/@humanwhocodes/config-array/api.js:966:42
at Array.reduce (<anonymous>)
at FlatConfigArray.getConfig (/Users/weiran/repo/github/eslint-plugin-node/node_modules/@humanwhocodes/config-array/api.js:965:39)
at FlatConfigArray.isFileIgnored (/Users/weiran/repo/github/eslint-plugin-node/node_modules/@humanwhocodes/config-array/api.js:993:15)
at /Users/weiran/repo/github/eslint-plugin-node/node_modules/eslint/lib/eslint/eslint-helpers.js:504:38
at Array.forEach (<anonymous>)
husky - pre-commit hook exited with code 1 (error) I suggest allowing the |
Allowing arbitrary The downside I was worried about with that is that ESLint stores some official properties in |
good point. |
Flat configs actually already support a I'm not sure it makes sense to standardize meta properties across all types of objects as they all have different purposes. Rules, necessarily, need more information because they are end-user-facing. Plugins adding |
name and description are conceptually distinct things; this feels to me like |
@ljharb are you suggesting that we just standardize a If so, how do we reconcile the existing |
Yes, and you can define “name and version” as something they aren’t allowed to do :-) I assume eslint would then add top-level properties when needed. |
I'm in favor of this. I think it'd be helpful for the ecosystem to collect the ad-hoc ways plugins document themselves into more standardized approaches. That way, tools like lintbased.com can improve discoverability of those plugins. For reference: in typescript-eslint, each user-facing config intentionally has a one-liner description in https://typescript-eslint.io/linting/configs#recommended-configurations. |
Okay, it seems like there's general agreement that this is a good idea, so marking as accepted. Does anyone want to take the action item to flesh out a full RFC? |
There seem to be some conflicting thoughts so far about whether user-defined properties should go in |
I'd say put together an RFC with your current thoughts and let people comment on that. It's a lot easier to have a full proposal to comment on then trying to peel off an individual preference here or there. |
ESLint version
v8.55.0
What problem do you want to solve?
With the new flat config system, configs are only allowed to export known properties like
rules
,files
, etc.However, in third-party tooling I maintain like eslint-doc-generator and lintbase.com, I've been letting plugins set an unofficial
description
/meta.description
/meta.docs.description
property to annotate their configs (or processors) with a description that can be included in the auto-generated documentation for the plugin. This won't work anymore as flat config will throw an error likeError: Unexpected key "meta" found.
.Furthermore, there are a variety of documentation-related properties used, allowed, or not allowed by ESLint core objects/concepts today, and this can be inconsistent and inflexible:
meta.name
andmeta.version
meta
ormeta.docs
,meta.docs.description
is commonly useddescription
name
property can be included to help with debuggingmeta.name
andmeta.version
for debuggingWhat do you think is the correct solution?
In general, it would be useful to be able to accommodate at least the following rule documentation properties on any of the ESLint-controlled core objects/concepts:
description
,url
,deprecated
,replacedBy
, plus space for arbitrary third-party/user-defined properties.The challenge is how to place these properties in a consistent fashion across object types and in consideration for the already existing properties.
In particular, some of these rule properties are spread across
meta
andmeta.docs
. The dividing line betweenmeta
andmeta.docs
can be a bit blurry. I was thinking thatmeta
would be for properties that are functionally used by ESLint, whereasmeta.docs
would be for non-critical/informational/custom properties that aren't necessarily used or needed by ESLint. By that division,description
,url
,deprecated
,replacedBy
would likely all fall undermeta.docs
.Some ideas for improving the consistency and flexibility of properties on ESLint core objects/concepts:
meta.docs
as an arbitrary object for any documentation / third-party properties.meta.docs
for documentation properties likedescription
,url
,deprecated
,replacedBy
.deprecated
andreplacedBy
directly onmeta
.name
orversion
is needed to be specified, include it in themeta
object. So we could update configs to acceptmeta.name
(falling back to the currentname
property for backwards compatibility if needed).To summarize: I took an initial stab at holistically considering documentation properties, but my top priority is really just to decide where documentation properties should go on each ESLint core object (in
meta.docs
in my proposal) without necessarily specifying a complete list of all potential documentation properties and their exact formats.Related issue about the deprecation properties:
Participation
Additional comments
No response
The text was updated successfully, but these errors were encountered: