Added usage and base configuration FAQs (#348)

* Added usage and base configuration FAQs

* Added little wink message

* Indeed, mentioned 880

* Update docs/FAQs.md

Co-Authored-By: Brad Zacher <[email protected]>

* Update docs/FAQs.md

Co-Authored-By: Brad Zacher <[email protected]>

* Moved zalgo down just a little bit

* There is no god

* Step one: tslint-to-eslint-config

Co-authored-by: Brad Zacher <[email protected]>

Author: Josh Goldberg

README.md

@@ -34,6 +34,10 @@ TSLint rules without ESLint equivalents will be wrapped with [eslint-plugin-tsli
 
 > Requires Node 10+ (LTS) and TSLint 5.18+
 
+### 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:

docs/FAQs.md

@@ -0,0 +1,41 @@
+# 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. 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. 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.
+
+## 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.
+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.
+
+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. 🙏

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}`);
     });
 });

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! 💖
+*/
+`;

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}`;
 };

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}`;
 };