From a00884bc8efc4943c47f04f64de4b1f843742434 Mon Sep 17 00:00:00 2001 From: "Nicholas C. Zakas" Date: Fri, 7 Jun 2024 11:29:01 -0400 Subject: [PATCH 1/5] docs: Decision docs for start of rewrite --- decisions/000-template.md | 12 ++++++++++++ decisions/001-rewrite-core.md | 24 ++++++++++++++++++++++++ decisions/002-javascript-jsdoc-tsc.md | 23 +++++++++++++++++++++++ decisions/003-esm.md | 19 +++++++++++++++++++ 4 files changed, 78 insertions(+) create mode 100644 decisions/000-template.md create mode 100644 decisions/001-rewrite-core.md create mode 100644 decisions/002-javascript-jsdoc-tsc.md create mode 100644 decisions/003-esm.md diff --git a/decisions/000-template.md b/decisions/000-template.md new file mode 100644 index 00000000..fdf1b8cd --- /dev/null +++ b/decisions/000-template.md @@ -0,0 +1,12 @@ +# Title + +Date: YYYY-MM-DD + +Status: proposed | rejected | accepted | deprecated | … | superseded by +[005](005-example.md) + +## Context + +## Decision + +## Consequences diff --git a/decisions/001-rewrite-core.md b/decisions/001-rewrite-core.md new file mode 100644 index 00000000..ff101aa6 --- /dev/null +++ b/decisions/001-rewrite-core.md @@ -0,0 +1,24 @@ +# Rewrite the ESLint Core + +Date: 2022-10-31 + +Status: accepted + +## Context + +ESLint was first released in 2013, meaning it will be ten years old next year. During that time, the way people write JavaScript has changed dramatically and we have been using the incremental approach to updating ESLint. This has served us well, as we've been able to keep up with changes fairly quickly while building off the same basic core as in 2013. However, the current core has several problems that prevent us from moving forward with key new features: + +1. **Synchronous core.** Because `Linter` is synchronous, that prevents us from allowing asynchronous rules and asynchronous parsers. +1. **Inflexible API design.** We have two APIs, `ESLint` and `Linter`, and we're forced to keep adding to these depending on use cases. For example, anything that needs to be accessible in the browser needs to be on `Linter` whether it makes sense API-wise or not. +1. **Node.js-centric.** People want to use ESLint in whatever environment they write JavaScript, whether that be a server runtime or in the browser. Being tied to the way Node.js does things prevents us from easily porting to other runtimes. +1. **JavaScript-centric.** There is a lot of logic tied to linting JavaScript when it doesn't have to be. The core should be language-agnostic. + +## Decision + +We will rewrite the ESLint core from scratch. The rewrite will happen in a separate repo so we can clearly distinguish between the rewritten functionality and the original. We will not aim for 100% feature parity with the original core from the start, but rather, will rebuild the core with the features we are sure we need and then rely on user feedback to identify gaps. + +## Consequences + +For a period of time, we will end up maintaining two versions of ESLint. This is a necessary step to ensure that we don't disrupt the normal flow of ESLint usage until we are certain that the new core is ready for production use. + +When the new core is ready, we will need to be careful about the migration plan for users as we don't want to alienate folks or make it seem like too big of a change. diff --git a/decisions/002-javascript-jsdoc-tsc.md b/decisions/002-javascript-jsdoc-tsc.md new file mode 100644 index 00000000..99d4b545 --- /dev/null +++ b/decisions/002-javascript-jsdoc-tsc.md @@ -0,0 +1,23 @@ +# Use JavaScript and JSDoc with tsc + +Date: 2022-10-31 + +Status: accepted + +## Context + +The [decision to rewrite the core](./001-rewrite-core.md) in a new repository brings with it the opportunity to do things differently, which naturally brought up the idea of rewriting the core in TypeScript. While TypeScript has advantages for many projects, the nature of ESLint makes this less appealing. + +The ESLint project is more than just the `eslint` CLI tool. It is also [Espree](https://github.com/eslint/espree), [`eslint-scope`](https://github.com/eslint/eslint-scope), and other utilities that ESLint uses to lint JavaScript code. Part of maintaining stability in ESLint is ESLint's ability to effectively test all of these utilities every time ESLint is run. Rewriting in TypeScript would necessarily mean switching to use [`typescript-eslint`](https://typescript-eslint.io) for linting out own project, which would mean we'd no longer be dogfooding our own utilities. + +## Decision + +The rewrite will use JavaScript and JSDoc comments along with `tsc` to enforce type checking. This allows ESLint to continue to dogfood its own parser, scope analyzer, and related tools without foregoing the type safety that TypeScript provides. We will use TypeScript for defining interfaces where necessary, as this is more convenient than JSDoc format, but not for functionality. + +Additionally, each package in the rewrite repository will publish their own types. + +## Consequences + +For the ESLint team, this represents an improvement over the current development process where the old core has no type checking. We will be able to catch more bugs during development time and finally have control over our own type definitions instead of whatever gets published to [DefinitelyTyped](https://definitelytyped.org/) without our knowledge. + +This may frustrate or anger folks who prefer to write TypeScript and may result in fewer outside contributions to ESLint. diff --git a/decisions/003-esm.md b/decisions/003-esm.md new file mode 100644 index 00000000..f843f58c --- /dev/null +++ b/decisions/003-esm.md @@ -0,0 +1,19 @@ +# Use and Target ESM + +Date: 2022-10-31 + +Status: accepted + +## Context + +ECMAScript Modules (ESM) have been a standard since 2015 and the move off of CommonJS is now well under way. Newer runtimes like Deno and Bun are ESM-only, most of web development is done in ESM. + +For all of ESLint's history, packages have been written and published in CommonJS, only sometimes providing an ESM entrypoint. + +## Decision + +All packages in the rewrite repository will be written in ESM and preferentially provide ESM entrypoints (where applicable). When possible, the packages will provide CommonJS entrypoints as well. + +## Consequences + +We will not be dogfood CommonJS-specific functionality in ESLint, so there is the possibility that some errors could creep in. We'll need to rely on our tests to catch these. From 3b14b39c6f203c7e24d5c9a0987ac7782b14390f Mon Sep 17 00:00:00 2001 From: "Nicholas C. Zakas" Date: Mon, 10 Jun 2024 10:49:05 -0400 Subject: [PATCH 2/5] Update decisions/003-esm.md Co-authored-by: Francesco Trotta --- decisions/003-esm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/decisions/003-esm.md b/decisions/003-esm.md index f843f58c..b4148ee3 100644 --- a/decisions/003-esm.md +++ b/decisions/003-esm.md @@ -16,4 +16,4 @@ All packages in the rewrite repository will be written in ESM and preferentially ## Consequences -We will not be dogfood CommonJS-specific functionality in ESLint, so there is the possibility that some errors could creep in. We'll need to rely on our tests to catch these. +We will not be dogfooding CommonJS-specific functionality in ESLint, so there is the possibility that some errors could creep in. We'll need to rely on our tests to catch these. From 0cae60feb57008fded38cf379fc9da0db7406cec Mon Sep 17 00:00:00 2001 From: "Nicholas C. Zakas" Date: Mon, 10 Jun 2024 10:51:12 -0400 Subject: [PATCH 3/5] Add link to GH discussion --- decisions/001-rewrite-core.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/decisions/001-rewrite-core.md b/decisions/001-rewrite-core.md index ff101aa6..e41a48ad 100644 --- a/decisions/001-rewrite-core.md +++ b/decisions/001-rewrite-core.md @@ -22,3 +22,7 @@ We will rewrite the ESLint core from scratch. The rewrite will happen in a separ For a period of time, we will end up maintaining two versions of ESLint. This is a necessary step to ensure that we don't disrupt the normal flow of ESLint usage until we are certain that the new core is ready for production use. When the new core is ready, we will need to be careful about the migration plan for users as we don't want to alienate folks or make it seem like too big of a change. + +## See Also + +- From 0005c7aecd14f6e5185ed410391ea9d9438390db Mon Sep 17 00:00:00 2001 From: "Nicholas C. Zakas" Date: Tue, 11 Jun 2024 10:23:36 -0400 Subject: [PATCH 4/5] Update decisions/002-javascript-jsdoc-tsc.md Co-authored-by: Milos Djermanovic --- decisions/002-javascript-jsdoc-tsc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/decisions/002-javascript-jsdoc-tsc.md b/decisions/002-javascript-jsdoc-tsc.md index 99d4b545..ffa2a2d5 100644 --- a/decisions/002-javascript-jsdoc-tsc.md +++ b/decisions/002-javascript-jsdoc-tsc.md @@ -8,7 +8,7 @@ Status: accepted The [decision to rewrite the core](./001-rewrite-core.md) in a new repository brings with it the opportunity to do things differently, which naturally brought up the idea of rewriting the core in TypeScript. While TypeScript has advantages for many projects, the nature of ESLint makes this less appealing. -The ESLint project is more than just the `eslint` CLI tool. It is also [Espree](https://github.com/eslint/espree), [`eslint-scope`](https://github.com/eslint/eslint-scope), and other utilities that ESLint uses to lint JavaScript code. Part of maintaining stability in ESLint is ESLint's ability to effectively test all of these utilities every time ESLint is run. Rewriting in TypeScript would necessarily mean switching to use [`typescript-eslint`](https://typescript-eslint.io) for linting out own project, which would mean we'd no longer be dogfooding our own utilities. +The ESLint project is more than just the `eslint` CLI tool. It is also [Espree](https://github.com/eslint/espree), [`eslint-scope`](https://github.com/eslint/eslint-scope), and other utilities that ESLint uses to lint JavaScript code. Part of maintaining stability in ESLint is ESLint's ability to effectively test all of these utilities every time ESLint is run. Rewriting in TypeScript would necessarily mean switching to use [`typescript-eslint`](https://typescript-eslint.io) for linting our own project, which would mean we'd no longer be dogfooding our own utilities. ## Decision From 2e3f7ba22d4928f2540a1a22e422ed5ed91c05a8 Mon Sep 17 00:00:00 2001 From: "Nicholas C. Zakas" Date: Tue, 11 Jun 2024 10:23:50 -0400 Subject: [PATCH 5/5] Update decisions/002-javascript-jsdoc-tsc.md Co-authored-by: Milos Djermanovic --- decisions/002-javascript-jsdoc-tsc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/decisions/002-javascript-jsdoc-tsc.md b/decisions/002-javascript-jsdoc-tsc.md index ffa2a2d5..e9890e4d 100644 --- a/decisions/002-javascript-jsdoc-tsc.md +++ b/decisions/002-javascript-jsdoc-tsc.md @@ -14,7 +14,7 @@ The ESLint project is more than just the `eslint` CLI tool. It is also [Espree]( The rewrite will use JavaScript and JSDoc comments along with `tsc` to enforce type checking. This allows ESLint to continue to dogfood its own parser, scope analyzer, and related tools without foregoing the type safety that TypeScript provides. We will use TypeScript for defining interfaces where necessary, as this is more convenient than JSDoc format, but not for functionality. -Additionally, each package in the rewrite repository will publish their own types. +Additionally, each package in the rewrite repository will publish its own types. ## Consequences