Docs: Add new experimental syntax policy to README (fixes #9804) #10408
Conversation
eslint-deprecated
bot
added
the
triage
platinumazure
added
documentation
|
TSC Summary: This pull requests attempts to clarify our README with the experimental feature policy suggested by Nicholas here: #9804 (comment) TSC Question: Does this PR capture the intent of the new policy accurately and clearly? Should we make this change? (Less importantly, are there other documentation areas that should be similarly changed?) |
|
The only thing that might not be captured here is, what about fixing a core rule that crashes with a non-default parser? Hopefully that's included in the intention of this change. |
Edit: I think it does, because Stage 3 features are (by our espree policy) not implemented in espree the default parser, so it would be any Stage 3 feature on a non-default parser. Other than Stage 3, popular language extensions are case by case (as stated) and Stage 0-2 proposals would be a no. |
README.md
Outdated
| ESLint doesn't natively support experimental ECMAScript language features. You can use [babel-eslint](https://github.com/babel/babel-eslint) to use any option available in Babel. | ||
| ESLint's parser only officially supports the latest final ECMAScript standard. We will make changes to core rules in order to avoid crashes on stage 3 ECMAScript syntax proposals. We may make changes to core rules to better work with language extensions (such as JSX, Flow, and TypeScript) on a case-by-case basis. | ||
|
|
||
| In other cases (including if rules need to warn on more or fewer cases due to new syntax, rather than just not crashing), you should use other parsers and/or rule plugins. If you are using Babel, you can use the [babel-eslint](https://github.com/babel/babel-eslint) parser and [eslint-plugin-babel](https://github.com/babel/eslint-plugin-babel) to use any option available in Babel. |
There was a problem hiding this comment.
This is very nitpicky, but I prefer we recommend you use other parsers and/or rule plugins to you should use other parsers and/or rule plugins, because I think it's a little friendlier!
There was a problem hiding this comment.
Agreed, I'll make that change.
There was a problem hiding this comment.
Sorry, I lied. Not sure I like that because this really is a (gentle) order to use something that isn't espree. How about please use other parsers and/or plugins? Or I can do your wording if you prefer.
There was a problem hiding this comment.
I prefer the wording I suggested, but I don't feel that strongly about it. Totally up to you :)
There was a problem hiding this comment.
I don't feel strongly about it, so I'll go with your wording. Expect a new commit shortly.
README.md
Outdated
| @@ -146,7 +146,9 @@ ESLint has full support for ECMAScript 3, 5 (default), 2015, 2016, 2017, and 201 | |||
|
|
|||
| ### What about experimental features? | |||
|
|
|||
| ESLint doesn't natively support experimental ECMAScript language features. You can use [babel-eslint](https://github.com/babel/babel-eslint) to use any option available in Babel. | |||
| ESLint's parser only officially supports the latest final ECMAScript standard. We will make changes to core rules in order to avoid crashes on stage 3 ECMAScript syntax proposals. We may make changes to core rules to better work with language extensions (such as JSX, Flow, and TypeScript) on a case-by-case basis. | |||
There was a problem hiding this comment.
As discussed in the TSC meeting, can you specify that not crashing in core rules is limited to ESTree's experimental AST representations for stage 3 syntax?
…tal features represented in ESTree
platinumazure
added
accepted
|
This was accepted in the 2018-06-07 TSC meeting. |
eslint-deprecated
bot
added
the
archived due to age
See #9804 (comment).
What is the purpose of this pull request? (put an "X" next to item)
[x] Documentation update
[ ] Bug fix (template)
[ ] New rule (template)
[ ] Changes an existing rule (template)
[ ] Add autofixing to a rule
[ ] Add a CLI option
[ ] Add something to the core
[x] Other, please explain: Applying a policy update, so may need to be discussed at TSC meeting.
What changes did you make? (Give an overview)
Updated README to clarify experimental language feature policy. Specifically, we accept PRs to avoid crashes (only) for Stage 3 issues; we otherwise require Stage 4 (as we have before now) for rule features and enhancements; and we treat language extensions on a case-by-case basis. (We could add more info about those language extensions in a later update, I think.)
Is there anything you'd like reviewers to focus on?
I used the language drafted by @nzakas in issue #9804, but we should review it carefully since this is basically a policy change. (Might need TSC discussion too, since we didn't have unanimous 👍 from all TSC on that issue, although we had no 👎 either.)