Skip to content

Commit e67721e

Browse files
committed
Docs: Add FAQ to README
1 parent c28fc0c commit e67721e

File tree

1 file changed

+23
-1
lines changed

1 file changed

+23
-1
lines changed

README.md

+23-1
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,7 @@ Espree may also deviate from Esprima in the interface it exposes.
102102

103103
## Frequent and Incremental Releases
104104

105-
Espree will not do giant releases. Releases will happen periodically as changes are made and incremental releases will be made towards larger goals. For instance, we will not have one big release for ECMAScript 6 support. Instead, we will implement ECMAScript 6, piece-by-piece, hiding those pieces behind an `ecmaVersion` property that you can opt-out of if you don't want to use those features.
105+
Espree will not do giant releases. Releases will happen periodically as changes are made and incremental releases will be made towards larger goals. For instance, we will not have one big release for ECMAScript 6 support. Instead, we will implement ECMAScript 6, piece-by-piece, hiding those pieces behind an `ecmaFeatures` property that allows you to opt-in to use those features.
106106

107107
## Contributing
108108

@@ -115,3 +115,25 @@ Espree is licensed under a permissive BSD 3-clause license.
115115
* `npm test` - run all linting and tests
116116
* `npm run lint` - run all linting
117117
* `npm run browserify` - creates a version of Espree that is usable in a browser
118+
119+
## Frequently Asked Questions
120+
121+
### Why are you forking Esprima?
122+
123+
[ESLint](http://eslint.org) has been relying on Esprima as its parser from the beginning. While that was fine when the JavaScript language was evolving slowly, the pace of development has increased dramatically and Esprima has fallen behind. ESLint, like many other tools reliant on Esprima, has been stuck in using new JavaScript language features until Esprima updates, and that has caused our users frustration.
124+
125+
We decided the only way for us to move forward was to create our own parser, bringing us inline with JSHint and JSLint, and allowing us to keep implementing new features as we need them. We chose to fork Esprima instead of starting from scratch in order to move as quickly as possible with a compatible API.
126+
127+
### Have you tried working with Esprima?
128+
129+
Yes. Since the start of ESLint, we've regularly filed bugs and feature requests with Esprima. Unfortunately, we've been unable to make much progress towards getting our needs addressed.
130+
131+
### Why don't you just use Facebook's Esprima fork?
132+
133+
`esprima-fb` is Facebook's Esprima fork that features JSX and Flow type annotations. We tried working with `esprima-fb` in our evaluation of how to support ECMAScript 6 and JSX in ESLint. Unfortunately, we were hampered by bugs that were part of Esprima (not necessarily Facebook's code). Since `esprima-fb` tracks the Esprima Harmony branch, that means we still were unable to get fixes or features we needed in a timely manner.
134+
135+
### Why don't you just use Acorn?
136+
137+
Acorn is a great JavaScript parser that produces an AST that is compatible with Esprima. Unfortunately, ESLint relies on more than just the AST to do its job. It relies on Esprima's tokens and comment attachment features to get a complete picture of the source code. We investigated switching to Acorn, but the inconsistencies between Esprima and Acorn created too much work for a project like ESLint.
138+
139+
We expect there are other tools like ESLint that rely on more than just the AST produced by Esprima, and so a drop-in replacement will help those projects as well as ESLint.

0 commit comments

Comments
 (0)