Merge pull request #26 from Mikek2252/main

Update README.md

README.md

@@ -1,56 +1,105 @@
 # Lint to the Future 🚀
 
-LintToTheFuture (LTTF) is a modern way to progressively update your entire codebase to the latest best practices. It has a number of tools that work together to manage linting rules and provides a sustainable way to add new rules to existing codebases without slowing down your development
+Lint to the Future (LTTF) is a useful tool that helps you to progressivly turn on or update lint rules in your codebase without making your test runner sad. LTTF allows you to move forward with linting without slowing your development down for even a second 🚀💪
+
+## How it works
+
+LTTF provides you with a few helpful tools but the two main ones that most people use regularly are the **ignore command** and the **Lint to the Future Dashboard**. 
+
+When you add a new lint rule to your codebase you will likely have many files that are reporting errors for this new rule. This is when you run the following command with Lint To The Future: 
+
+```
+npx lint-to-the-future ignore
+```
+
+and it will automatically add **file-based ignore directives** to each of the files that were previously failing your lint command. These file-based ignore directives are intended to be temporary and you can come back to fix the files later, while making sure that any new file you create has to abide by the new lint rule you added 🎉
+
+When you are done adding file-based ignore directives to each of your files you can put together a dashboard that keeps track of which files you still need to come back and fix. The dashboard looks like this
+
+![ember-learn github io_ember-styleguide_](https://user-images.githubusercontent.com/594890/193256435-0355d6be-c39f-4901-89a1-58dd6b871129.png)
+
+
+Keep reading to find out how to set it up 📚
 
 ## Installation
 
-You should install this as a dev-dependency of your project
+You should install Lint to the Future as a dev-dependency of your project
 
 ```
 npm i --save-dev lint-to-the-future
 ```
 
-on its own LTTF doesn't do anything by itself, you should also install some plugins. The first plugin written for LTTF was the eslint plugin which you can install using the following:
+on its own LTTF doesn't do anything by itself, so you should also install some plugins. If you're using eslint on your project you can install the plugin for it using the following:
 
 ```
 npm i --save-dev lint-to-the-future-eslint
 ```
 
 ### Plugins
 
-LTTF will automatically load each plugin (any package you have installed locally starting with `lint-to-the-future-`) and run them in order.
+LTTF will automatically load each plugin (any package you have installed locally starting with `lint-to-the-future-`) and run them in one after another.
 
 You can write your own plugin, or use one from the existing list:
 
 - For Ember apps: [`lint-to-the-future-ember-template`](/~https://github.com/mansona/lint-to-the-future-ember-template)
 - For all JavaScript apps: [`lint-to-the-future-eslint`](/~https://github.com/mansona/lint-to-the-future-eslint)
 - For styles [`lint-to-the-future-stylelint`](/~https://github.com/mansona/lint-to-the-future-stylelint)
 
-To find out some more information about how to write your own plugin, check out the [plugin docs](./docs/plugin-development.md).
+To find out some more information about how to write your own plugin, check out the [plugin docs](/docs/plugin-development.md).
 
 ## Usage
 
-This project is still in alpha phase, so we will add new sub-sections to Usage as they have been implemented. If you are interested in this project feel free to reach out to me on Twitter at [@real_ate](https://twitter.com/real_ate).
+I've already given a quick overview on how to use Lint to the Future above but let's go into a bit more detail.
 
 ### Adding file-based lint ignores to your project
 
-Using the `eslint` plugin as an example: running the cli application will automatically run `eslint` on your codebase and add file-based ignores to that file.
+Let's use the `eslint` plugin as an example. The first thing you need to do is to make sure that running `eslint` on your project actually shows some linting errors. Lint to the Future is intended to be used to fix linting situations that are **currently erroring** so make sure you configure your eslint to throw some errors if you want to test it out. Running the ignore command will automatically run `eslint` on your codebase and add file-based ignores to any file that is currently erroring:
 
 ```
 npx lint-to-the-future ignore
 ```
 
-After running this process you should be able to run `eslint` on your project again and it will show no more errors.
+After running this process you should be able to run `eslint` again on your project again and it will show no more errors 💪
 
 **Note:** we don't currently add file-based ignores for warnings as they don't generally break CI in the most common configurations.
 
+## Lint to the Future Dashboard
+
+The **file-based ignore directives** that Lint to the Future adds are supposed to be temporary, so Lint to the Future can generate a dashboard that helps you keep track of files that still have ignore directives in them and also keeps track how you are progressing with removals over time.
+
+To see it in action, check out [ember-styleguide's dashboard](https://ember-learn.github.io/ember-styleguide/)
+
+The easiest way to set up the Lint to the Future Dashboard is to use the [lint-to-the-future-dashboard-action](/~https://github.com/mansona/lint-to-the-future-dashboard-action) if you are hosting your code on GitHub and don't mind your dashboard being public on GitHub Pages. You can read the README of the that project to find out more about it but the easist way to get started is to create a file called `.github/lint-to-the-future.yml` and add the following to that file: 
+
+```yml
+name: Lint to the Future Dashboard
+
+on:
+  push:
+    branches:
+      - master
+      - main
+
+jobs:
+  deploy:
+    uses: mansona/lint-to-the-future-dashboard-action/.github/workflows/dashboard.yml@main
+    with:
+      folder: ''
+```
+
+And that will start updating your dashboard when you push something to your master or main branch 🎉 Just remember to enable GitHub pages for your repo on the `gh-pages` branch 👍
+
+If you want to deploy your dashboard in any other way then you should check out the [dashboard deployment](/docs/dashboard-deployment.md) documentation.
+
+**Note:** if you're thinking that you need to use the manual deployment documentation because you want to deploy your dashboard privately then be aware that there is no real data form your codebase that is exposed via the Lint to the Future Dashboard. The most identifiable information that could be exposed is the **file names** of any file that has an igore directive in it, which in the vast majority of cases should provide no security risk 👍
+
 ## Frequently Asked Questions
 
 ### Why do you use file based ignores instead of line-based or projected-wide
 
-The point of LintToTheFuture is to allow you to **progressively** update your codebase using new lint rules without overwhelming you with the task. You can easily ignore lint rules using project-based ignores in your config files but that doesn't prevent you from making the same errors in new files.
+The point of Lint to the Future is to allow you to **progressively** update your codebase using new lint rules without overwhelming you with the task. You can easily ignore lint rules using project-based ignores in your config files but that doesn't prevent you from making the same errors in new files.
 
-We chose to do the ignores on a file basis as it is a perfect balance and it means that the tracking/graphing aspects of LintToTheFuture provide you with achievable goals, especially in large codebases.
+We chose to do the ignores on a file basis as it is a perfect balance and it means that the tracking/graphing aspects of Lint to the Future provide you with achievable goals, especially in large codebases.
 
 ### Why would you run this instead of just running `lint fix` to fix as many problems as possible
 

docs/dashboard-deployment.md

@@ -0,0 +1,29 @@
+# Lint to the Future - Dashboard Deployment
+
+This documentation is for **manual deployment** of the Lint to the Future dashboard. The **vast** majority of people do not need to know how to deploy things in this level of detail and should just follow the basic instructions in the [main README file](/README.md)
+
+**Note:** this is work-in-progress document and if you have any improvements to it please feel free to open a PR 👍
+
+## Setting up the dashboard for manual deployment
+
+The following command can run within your application directory and will generate the dashboard web application and take a data snapshot of your current lint disables. If you have previous results, it will collate them to create a graph over time.
+
+```
+npx lint-to-the-future output -o <output-dir> --rootUrl <root-url> --previous-results <path-to-previous-results>
+```
+
+```
+-o <required>
+  This argument specifies the output directory of dashboard application.
+
+--rootUrl <optional>
+  This argument is required if the dashboard is not hosted on your servers rootUrl.
+  e.g. the ember-styleguide dashboard URL is https://ember-learn.github.io/ember-styleguide/ so --rootUrl ember-styleguide is required
+
+--previous-results <optional>
+  This argument can accept either a local path or a URL.
+  As the name suggests this should be a path or URL to the previous data.json file that was generated when this command was last run.
+  This argument is only required if you want historical data.
+```
+
+After sucessfully running the command you will have the dashboard application generated in your chosen directory ready to be deployed to your chosen environment.