From e41ab5e294e59ef40345e8c9a60ac485c7e5f7d5 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Sat, 28 Mar 2020 00:09:49 -0400 Subject: [PATCH 1/8] Added usage and base configuration FAQs --- README.md | 6 +++- docs/FAQs.md | 34 +++++++++++++++++++ src/creation/formatting/formatOutput.test.ts | 9 ++--- src/creation/formatting/formatters/faqs.ts | 14 ++++++++ .../formatting/formatters/formatJsOutput.ts | 7 +++- .../formatting/formatters/formatJsonOutput.ts | 3 +- 6 files changed, 66 insertions(+), 7 deletions(-) create mode 100644 docs/FAQs.md create mode 100644 src/creation/formatting/formatters/faqs.ts diff --git a/README.md b/README.md index c8a89e463..20b828c7d 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ ![Coverage: 100%](https://img.shields.io/badge/coverage-100%25-orange.svg) ![TypeScript: Strict](https://img.shields.io/badge/typescript-strict-yellow.svg) [![NPM version](https://badge.fury.io/js/tslint-to-eslint-config.svg)](http://badge.fury.io/js/tslint-to-eslint-config) -[![Circle CI](https://img.shields.io/circleci/build/github/typescript-eslint/tslint-to-eslint-config.svg)](https://circleci.com/gh/typescript-eslint/tslint-to-eslint-config) +[![Circle CI](https://img.shields.io/circleci/build/github/typescript-eslint/tslint-to-eslint-config.svg)](https://circleci.com/gh/typescript-eslint/tslint-to-eslint-config) [![Join the chat at https://gitter.im/tslint-to-eslint-config/community](https://img.shields.io/badge/chat-gitter-informational.svg)](https://gitter.im/tslint-to-eslint-config/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Code Style: Prettier](https://img.shields.io/badge/speed-blazingly_fast-blueviolet.svg)](https://prettier.io) @@ -34,6 +34,10 @@ TSLint rules without ESLint equivalents will be wrapped with [eslint-plugin-tsli > Requires Node 8+ (LTS) +### FAQs + +We **strongly** advise reading [docs/FAQs.md](./docs/FAQs.md) before planning your conversion from ESLint to TSLint. + ### CLI Flags Each of these flags is optional: diff --git a/docs/FAQs.md b/docs/FAQs.md new file mode 100644 index 000000000..cd9ac1994 --- /dev/null +++ b/docs/FAQs.md @@ -0,0 +1,34 @@ +# Frequently Asked Questions + +## Should I Migrate from TSLint to ESLint? + +**Yes**. + +[TSLint is deprecated](https://medium.com/palantir/tslint-in-2019-1a144c2317a9) and will [only receive patches](https://github.com/palantir/tslint/issues/4534) for security vulnerabilities and breaking TypeScript changes. +Even if it still works on your project, it will become less useful over time as TypeScript evolves. + +## Should I Use `tslint-to-eslint-config`? + +`tslint-to-eslint-config` is recommended for use if you require near-identical behavior in transitioning from TSLint to ESLint. +This is most reasonable when your project is large enough that fixing for different linter rules would be a significant time investment. + +However, after -or even better, _before_- you're migrated to ESLint, we recommend you take this opportunity to re-evaluate your core lint rules. +TSLint's recommendations were solidified several core TypeScript versions ago and don't always reflect the latest and greatest standards and lint rules. + +Our recommended TSLint-to-ESLint configuration migration approach is: + +1. Switch your configuration to extend from [typescript-eslint's `recommended` and `recommend-requiring-type-checking` rulesets](https://github.com/typescript-eslint/typescript-eslint/blob/master/docs/getting-started/linting/README.md) +2. [Disable complaints on a line-, file-, or rule basis](https://eslint.org/docs/user-guide/configuring) for any rules you do not want to enable and/or are now giving complaints +3. Add any [community plugins](https://github.com/typescript-eslint/typescript-eslint/blob/master/docs/getting-started/linting/README.md#plugins) relevant to your project, then repeat step 2 + +## Should I Use Prettier? + +**Yes**. + +Formatting responsibilities, such as indentation and line wrapping, are exceedingly difficult to get implement in **linters**, and as such are practically impossible to get correct in them. +**Formatters** such as [Prettier](https://prettier.io) do a [much better job](https://prettier.io/docs/en/why-prettier.html) of formatting your code. + +The maintenance teams at both TSLint and typescript-eslint recommend using a formatter such as Prettier to format your code instead of a linter. + +> 🙏 [eslint-plugin-prettier](https://github.com/typescript-eslint/typescript-eslint/blob/master/docs/getting-started/linting/README.md#usage-with-prettier) is an excellent ESLint plugin that disables formatting rules from your configuration. +> Please use it. 🙏 diff --git a/src/creation/formatting/formatOutput.test.ts b/src/creation/formatting/formatOutput.test.ts index 422c16169..9a6a2391b 100644 --- a/src/creation/formatting/formatOutput.test.ts +++ b/src/creation/formatting/formatOutput.test.ts @@ -1,5 +1,6 @@ import { EOL } from "os"; +import { faqs } from "./formatters/faqs"; import { formatOutput } from "./formatOutput"; describe("formatOutput", () => { @@ -13,7 +14,7 @@ describe("formatOutput", () => { // Assert expect(output).toBe( - `module.exports = ${JSON.stringify(configuration, undefined, 4)};${EOL}`, + `${faqs}module.exports = ${JSON.stringify(configuration, undefined, 4)};${EOL}`, ); }); @@ -26,7 +27,7 @@ describe("formatOutput", () => { const output = formatOutput(outputPath, configuration); // Assert - expect(output).toBe(`${JSON.stringify(configuration, undefined, 4)}${EOL}`); + expect(output).toBe(`${faqs}${JSON.stringify(configuration, undefined, 4)}${EOL}`); }); it("formats output as JSON for an unknown dot file path", () => { @@ -38,7 +39,7 @@ describe("formatOutput", () => { const output = formatOutput(outputPath, configuration); // Assert - expect(output).toBe(`${JSON.stringify(configuration, undefined, 4)}${EOL}`); + expect(output).toBe(`${faqs}${JSON.stringify(configuration, undefined, 4)}${EOL}`); }); it("formats output as JSON for an unknown raw file path", () => { @@ -50,6 +51,6 @@ describe("formatOutput", () => { const output = formatOutput(outputPath, configuration); // Assert - expect(output).toBe(`${JSON.stringify(configuration, undefined, 4)}${EOL}`); + expect(output).toBe(`${faqs}${JSON.stringify(configuration, undefined, 4)}${EOL}`); }); }); diff --git a/src/creation/formatting/formatters/faqs.ts b/src/creation/formatting/formatters/faqs.ts new file mode 100644 index 000000000..87efec0fb --- /dev/null +++ b/src/creation/formatting/formatters/faqs.ts @@ -0,0 +1,14 @@ +export const faqs = `/* +👋 Hi! This file was autogenerated by tslint-to-eslint-config. +https://github.com/typescript-eslint/tslint-to-eslint-config + +It represents the closest reasonable ESLint configuration to this +project's original TSLint configuration. + +We recommend eventually switching this configuration to extend from +the recommended rulesets in typescript-eslint. +https://github.com/typescript-eslint/tslint-to-eslint-config/blob/master/docs/FAQs.md + +Happy linting! 💖 +*/ +`; diff --git a/src/creation/formatting/formatters/formatJsOutput.ts b/src/creation/formatting/formatters/formatJsOutput.ts index 23bc78f29..d9095be1f 100644 --- a/src/creation/formatting/formatters/formatJsOutput.ts +++ b/src/creation/formatting/formatters/formatJsOutput.ts @@ -1,7 +1,12 @@ import { EOL } from "os"; +import { faqs } from "./faqs"; import { withKeysSorted } from "./withKeysSorted"; export const formatJsOutput = (configuration: any) => { - return `module.exports = ${JSON.stringify(withKeysSorted(configuration), undefined, 4)};${EOL}`; + return `${faqs}module.exports = ${JSON.stringify( + withKeysSorted(configuration), + undefined, + 4, + )};${EOL}`; }; diff --git a/src/creation/formatting/formatters/formatJsonOutput.ts b/src/creation/formatting/formatters/formatJsonOutput.ts index 16298f1d2..069269a81 100644 --- a/src/creation/formatting/formatters/formatJsonOutput.ts +++ b/src/creation/formatting/formatters/formatJsonOutput.ts @@ -1,7 +1,8 @@ import { EOL } from "os"; +import { faqs } from "./faqs"; import { withKeysSorted } from "./withKeysSorted"; export const formatJsonOutput = (configuration: any) => { - return `${JSON.stringify(withKeysSorted(configuration), undefined, 4)}${EOL}`; + return `${faqs}${JSON.stringify(withKeysSorted(configuration), undefined, 4)}${EOL}`; }; From 91a8c01468c9c36cb9f299b2c5df31f4433b5bd5 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Sat, 28 Mar 2020 00:28:15 -0400 Subject: [PATCH 2/8] Added little wink message --- docs/FAQs.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/FAQs.md b/docs/FAQs.md index cd9ac1994..535a42d3b 100644 --- a/docs/FAQs.md +++ b/docs/FAQs.md @@ -21,6 +21,8 @@ Our recommended TSLint-to-ESLint configuration migration approach is: 2. [Disable complaints on a line-, file-, or rule basis](https://eslint.org/docs/user-guide/configuring) for any rules you do not want to enable and/or are now giving complaints 3. Add any [community plugins](https://github.com/typescript-eslint/typescript-eslint/blob/master/docs/getting-started/linting/README.md#plugins) relevant to your project, then repeat step 2 +> 😉 Consider filing granular tickets to track investigating re-enabling disabled lint rules to make sure the work doesn't get forgotten. + ## Should I Use Prettier? **Yes**. From f968c2d8b5d78a8d600c7502f62edae4aa881294 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Mon, 30 Mar 2020 07:19:14 -0400 Subject: [PATCH 3/8] Indeed, mentioned 880 --- docs/FAQs.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/FAQs.md b/docs/FAQs.md index 535a42d3b..d5d16f3fc 100644 --- a/docs/FAQs.md +++ b/docs/FAQs.md @@ -29,6 +29,7 @@ Our recommended TSLint-to-ESLint configuration migration approach is: Formatting responsibilities, such as indentation and line wrapping, are exceedingly difficult to get implement in **linters**, and as such are practically impossible to get correct in them. **Formatters** such as [Prettier](https://prettier.io) do a [much better job](https://prettier.io/docs/en/why-prettier.html) of formatting your code. +See [this issue](https://github.com/typescript-eslint/typescript-eslint/issues/880) for more explanation. The maintenance teams at both TSLint and typescript-eslint recommend using a formatter such as Prettier to format your code instead of a linter. From c00a845eef5128488ff0e8935d04e5d562c5f3a5 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Mon, 30 Mar 2020 15:46:31 -0400 Subject: [PATCH 4/8] Update docs/FAQs.md Co-Authored-By: Brad Zacher --- docs/FAQs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/FAQs.md b/docs/FAQs.md index d5d16f3fc..5db5460eb 100644 --- a/docs/FAQs.md +++ b/docs/FAQs.md @@ -29,7 +29,7 @@ Our recommended TSLint-to-ESLint configuration migration approach is: Formatting responsibilities, such as indentation and line wrapping, are exceedingly difficult to get implement in **linters**, and as such are practically impossible to get correct in them. **Formatters** such as [Prettier](https://prettier.io) do a [much better job](https://prettier.io/docs/en/why-prettier.html) of formatting your code. -See [this issue](https://github.com/typescript-eslint/typescript-eslint/issues/880) for more explanation. +See [this issue](https://github.com/typescript-eslint/typescript-eslint/issues/1824) for more explanation. The maintenance teams at both TSLint and typescript-eslint recommend using a formatter such as Prettier to format your code instead of a linter. From 0bb864a8d1a22228aeb80d6cec10cb22146d567c Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Mon, 30 Mar 2020 15:49:09 -0400 Subject: [PATCH 5/8] Update docs/FAQs.md Co-Authored-By: Brad Zacher --- docs/FAQs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/FAQs.md b/docs/FAQs.md index 5db5460eb..05d7c94ed 100644 --- a/docs/FAQs.md +++ b/docs/FAQs.md @@ -25,7 +25,7 @@ Our recommended TSLint-to-ESLint configuration migration approach is: ## Should I Use Prettier? -**Yes**. +**Yes, god yes. Please do it. Now. Please stop using code style rules. Please use prettier. Code style rules are hard to write and maintain. Rules like indent are thousands of he comes he comes do not fi​ght he com̡e̶s, ̕h̵i​s un̨ho͞ly radiańcé destro҉ying all enli̍̈́̂̈́ghtenment, spaces and brackets lea͠ki̧n͘g fr̶ǫm ̡yo​͟ur eye͢s̸ ̛l̕ik͏e liq​uid pain, the song of indentation calculation will exti​nguish the voices of mor​tal man from the sp​here I can see it can you see ̲͚̖͔̙î̩́t̲͎̩̱͔́̋̀ it is beautiful t​he final snuffing of the lie​s of Man ALL IS LOŚ͖̩͇̗̪̏̈́T ALL I​S LOST the pon̷y he comes he c̶̮omes he comes the ich​or permeates all MY FACE MY FACE ᵒh god no NO NOO̼O​O NΘ stop the an​*̶͑̾̾​̅ͫ͏̙̤g͇̫͛͆̾ͫ̑͆l͖͉̗̩̳̟̍ͫͥͨe̠̅s ͎a̧͈͖r̽̾̈́͒͑e n​ot rè̑ͧ̌aͨl̘̝̙̃ͤ͂̾̆ ZA̡͊͠͝LGΌ ISͮ̂҉̯͈͕̹̘̱ TO͇̹̺ͅƝ̴ȳ̳ TH̘Ë͖́̉ ͠P̯͍̭O̚​N̐Y̡ H̸̡̪̯ͨ͊̽̅̾̎Ȩ̬̩̾͛ͪ̈́̀́͘ ̶̧̨̱̹̭̯ͧ̾ͬC̷̙̲̝͖ͭ̏ͥͮ͟Oͮ͏̮̪̝͍M̲̖͊̒ͪͩͬ̚̚͜Ȇ̴̟̟͙̞ͩ͌͝S̨̥̫͎̭ͯ̿̔̀ͅ**. Formatting responsibilities, such as indentation and line wrapping, are exceedingly difficult to get implement in **linters**, and as such are practically impossible to get correct in them. **Formatters** such as [Prettier](https://prettier.io) do a [much better job](https://prettier.io/docs/en/why-prettier.html) of formatting your code. From ef3d25188f2d2fe8be358c03768e159b68592ee6 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Mon, 30 Mar 2020 15:50:07 -0400 Subject: [PATCH 6/8] Moved zalgo down just a little bit --- docs/FAQs.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/FAQs.md b/docs/FAQs.md index 05d7c94ed..7cf0ad4e1 100644 --- a/docs/FAQs.md +++ b/docs/FAQs.md @@ -25,7 +25,7 @@ Our recommended TSLint-to-ESLint configuration migration approach is: ## Should I Use Prettier? -**Yes, god yes. Please do it. Now. Please stop using code style rules. Please use prettier. Code style rules are hard to write and maintain. Rules like indent are thousands of he comes he comes do not fi​ght he com̡e̶s, ̕h̵i​s un̨ho͞ly radiańcé destro҉ying all enli̍̈́̂̈́ghtenment, spaces and brackets lea͠ki̧n͘g fr̶ǫm ̡yo​͟ur eye͢s̸ ̛l̕ik͏e liq​uid pain, the song of indentation calculation will exti​nguish the voices of mor​tal man from the sp​here I can see it can you see ̲͚̖͔̙î̩́t̲͎̩̱͔́̋̀ it is beautiful t​he final snuffing of the lie​s of Man ALL IS LOŚ͖̩͇̗̪̏̈́T ALL I​S LOST the pon̷y he comes he c̶̮omes he comes the ich​or permeates all MY FACE MY FACE ᵒh god no NO NOO̼O​O NΘ stop the an​*̶͑̾̾​̅ͫ͏̙̤g͇̫͛͆̾ͫ̑͆l͖͉̗̩̳̟̍ͫͥͨe̠̅s ͎a̧͈͖r̽̾̈́͒͑e n​ot rè̑ͧ̌aͨl̘̝̙̃ͤ͂̾̆ ZA̡͊͠͝LGΌ ISͮ̂҉̯͈͕̹̘̱ TO͇̹̺ͅƝ̴ȳ̳ TH̘Ë͖́̉ ͠P̯͍̭O̚​N̐Y̡ H̸̡̪̯ͨ͊̽̅̾̎Ȩ̬̩̾͛ͪ̈́̀́͘ ̶̧̨̱̹̭̯ͧ̾ͬC̷̙̲̝͖ͭ̏ͥͮ͟Oͮ͏̮̪̝͍M̲̖͊̒ͪͩͬ̚̚͜Ȇ̴̟̟͙̞ͩ͌͝S̨̥̫͎̭ͯ̿̔̀ͅ**. +**Yes, god yes** Formatting responsibilities, such as indentation and line wrapping, are exceedingly difficult to get implement in **linters**, and as such are practically impossible to get correct in them. **Formatters** such as [Prettier](https://prettier.io) do a [much better job](https://prettier.io/docs/en/why-prettier.html) of formatting your code. @@ -33,5 +33,7 @@ See [this issue](https://github.com/typescript-eslint/typescript-eslint/issues/1 The maintenance teams at both TSLint and typescript-eslint recommend using a formatter such as Prettier to format your code instead of a linter. +Please do it. Now. Please stop using code style rules. Please use prettier. Code style rules are hard to write and maintain. Rules like indent are thousands of he comes he comes do not fi​ght he com̡e̶s, ̕h̵i​s un̨ho͞ly radiańcé destro҉ying all enli̍̈́̂̈́ghtenment, spaces and brackets lea͠ki̧n͘g fr̶ǫm ̡yo​͟ur eye͢s̸ ̛l̕ik͏e liq​uid pain, the song of indentation calculation will exti​nguish the voices of mor​tal man from the sp​here I can see it can you see ̲͚̖͔̙î̩́t̲͎̩̱͔́̋̀ it is beautiful t​he final snuffing of the lie​s of Man ALL IS LOŚ͖̩͇̗̪̏̈́T ALL I​S LOST the pon̷y he comes he c̶̮omes he comes the ich​or permeates all MY FACE MY FACE ᵒh god no NO NOO̼O​O NΘ stop the an​*̶͑̾̾​̅ͫ͏̙̤g͇̫͛͆̾ͫ̑͆l͖͉̗̩̳̟̍ͫͥͨe̠̅s ͎a̧͈͖r̽̾̈́͒͑e n​ot rè̑ͧ̌aͨl̘̝̙̃ͤ͂̾̆ ZA̡͊͠͝LGΌ ISͮ̂҉̯͈͕̹̘̱ TO͇̹̺ͅƝ̴ȳ̳ TH̘Ë͖́̉ ͠P̯͍̭O̚​N̐Y̡ H̸̡̪̯ͨ͊̽̅̾̎Ȩ̬̩̾͛ͪ̈́̀́͘ ̶̧̨̱̹̭̯ͧ̾ͬC̷̙̲̝͖ͭ̏ͥͮ͟Oͮ͏̮̪̝͍M̲̖͊̒ͪͩͬ̚̚͜Ȇ̴̟̟͙̞ͩ͌͝S̨̥̫͎̭ͯ̿̔̀ͅ. + > 🙏 [eslint-plugin-prettier](https://github.com/typescript-eslint/typescript-eslint/blob/master/docs/getting-started/linting/README.md#usage-with-prettier) is an excellent ESLint plugin that disables formatting rules from your configuration. > Please use it. 🙏 From 401b30fe1f9dba13bb7f8628f2994d470ce1562e Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Mon, 30 Mar 2020 15:50:39 -0400 Subject: [PATCH 7/8] There is no god --- docs/FAQs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/FAQs.md b/docs/FAQs.md index 7cf0ad4e1..a1ee7af42 100644 --- a/docs/FAQs.md +++ b/docs/FAQs.md @@ -25,7 +25,7 @@ Our recommended TSLint-to-ESLint configuration migration approach is: ## Should I Use Prettier? -**Yes, god yes** +**Yes!** Formatting responsibilities, such as indentation and line wrapping, are exceedingly difficult to get implement in **linters**, and as such are practically impossible to get correct in them. **Formatters** such as [Prettier](https://prettier.io) do a [much better job](https://prettier.io/docs/en/why-prettier.html) of formatting your code. From 09cff32a7a92c8f655e085438c511b1ab8bedb2b Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Mon, 30 Mar 2020 15:52:51 -0400 Subject: [PATCH 8/8] Step one: tslint-to-eslint-config --- docs/FAQs.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/FAQs.md b/docs/FAQs.md index a1ee7af42..9249dea7e 100644 --- a/docs/FAQs.md +++ b/docs/FAQs.md @@ -17,9 +17,11 @@ TSLint's recommendations were solidified several core TypeScript versions ago an Our recommended TSLint-to-ESLint configuration migration approach is: -1. Switch your configuration to extend from [typescript-eslint's `recommended` and `recommend-requiring-type-checking` rulesets](https://github.com/typescript-eslint/typescript-eslint/blob/master/docs/getting-started/linting/README.md) +1. Run `tslint-to-eslint-config` on your project 2. [Disable complaints on a line-, file-, or rule basis](https://eslint.org/docs/user-guide/configuring) for any rules you do not want to enable and/or are now giving complaints -3. Add any [community plugins](https://github.com/typescript-eslint/typescript-eslint/blob/master/docs/getting-started/linting/README.md#plugins) relevant to your project, then repeat step 2 +3. Switch your configuration to extend from [typescript-eslint's `recommended` and `recommend-requiring-type-checking` rulesets](https://github.com/typescript-eslint/typescript-eslint/blob/master/docs/getting-started/linting/README.md) +4. Repeat step 2 +5. Add any [community plugins](https://github.com/typescript-eslint/typescript-eslint/blob/master/docs/getting-started/linting/README.md#plugins) relevant to your project, then repeat step 2 > 😉 Consider filing granular tickets to track investigating re-enabling disabled lint rules to make sure the work doesn't get forgotten.