Added usage and base configuration FAQs

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:

docs/FAQs.md

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

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