Adds --baseline docs

CHANGELOG.md

@@ -16,7 +16,7 @@ removing dependencies that can be removed, and fixing bugs.
 
 There are breaking changes ahead!
 
-We also have this [nice migration guide](https://wemake-python-stylegui.de/en/latest/pages/changelog/migration_to_0_14.html).
+We also have this [0.14 migration guide](https://wemake-python-stylegui.de/en/latest/pages/changelog/migration_to_0_14.html).
 
 ### Features
 
@@ -461,7 +461,7 @@ We had to fix it before it is too late.
 So, we broke existing error codes.
 And now we can promise not to do it ever again.
 
-We also have this [nice migration guide](https://wemake-python-stylegui.de/en/latest/pages/changelog/migration_to_0_11.html)
+We also have this [0.11 migration guide](https://wemake-python-stylegui.de/en/latest/pages/changelog/migration_to_0_11.html)
 for you to rename your violations with a script.
 
 ### Features

README.md

@@ -30,16 +30,11 @@ pip install wemake-python-styleguide
 
 You will also need to create a `setup.cfg` file with the [configuration](https://wemake-python-stylegui.de/en/latest/pages/usage/configuration.html).
 
-We highly recommend to also use:
-
-- [flakehell](https://wemake-python-stylegui.de/en/latest/pages/usage/integrations/flakehell.html) for easy integration into a **legacy** codebase
-- [nitpick](https://wemake-python-stylegui.de/en/latest/pages/usage/integrations/nitpick.html) for sharing and validating configuration across multiple projects
-
 
 ## Running
 
 ```bash
-flake8 your_module.py
+flake8 your_project
 ```
 
 This app is still just good old `flake8`!
@@ -50,6 +45,17 @@ And it won't change your existing workflow.
        alt="invocation resuts">
 </p>
 
+We also support just a **single command**
+for [incremental adoption](https://wemake-python-stylegui.de/en/latest/pages/usage/setup.html#incremental-adoption)
+of this linter into any existing codebase:
+
+```bash
+flake8 --baseline your_project
+```
+
+Done! Now linter will not report any old violations.
+And will only report new ones created after the baseline was generated.
+
 See ["Usage" section](https://wemake-python-stylegui.de/en/latest/pages/usage/setup.html)
 in the docs for examples and integrations.
 

docs/pages/usage/integrations/index.rst

@@ -1,12 +1,11 @@
 .. toctree::
   :hidden:
 
+  legacy.rst
   plugins.rst
   editors.rst
   auto-formatters.rst
   nitpick.rst
-  legacy.rst
-  flakehell.rst
   docker.rst
   github-actions.rst
   ci.rst

docs/pages/usage/integrations/legacy.rst

@@ -1,30 +1,103 @@
 .. _legacy:
 
 Legacy projects
----------------
+===============
 
 Introducing this package to a legacy project is going to be a challenge.
 Due to our strict quality, consistency, and complexity rules.
 
 But, you still can do several things to integrate this linter step by step:
 
-1. Fix consistency, naming and best-practices violations,
+1. Generate a baseline to ignore existing violations
+   and only report new ones that were created after the baseline.
+2. Fix consistency, naming and best-practices violations,
    they are the easiest to clean up.
-2. Per-file ignore complexity checks that are failing for your project.
+3. Per-file ignore complexity checks that are failing for your project.
    Sometimes it is possible to rewrite several parts of your code,
    but generally complexity rules are the hardest to fix.
-3. Use `boyscout rule <https://deviq.com/boy-scout-rule/>`_: always leave
+4. Use `boyscout rule <https://deviq.com/boy-scout-rule/>`_: always leave
    your code better than you found it.
 
 To make sure "boyscout rule" works we offically support ``--diff`` mode.
 The main idea of it is simple: we only lint things that we touch.
 
-We also support :ref:`flakehell-legacy` (external tool)
-to create a ``baseline`` of your currect violations
-and start to lint only new one from this point.
-
 Choose what suits you best.
 
+.. _baseline:
+
+Baseline
+--------
+
+You can start using it with just a single command!
+
+.. code:: bash
+
+  flake8 --baseline your_project
+
+This guide will explain how it works.
+
+Steps
+~~~~~
+
+There are several steps in how baseline works.
+
+We can run the linter with ``--baseline`` mode enabled.
+What will happen?
+
+If you don't have ``.flake8-baseline.json``,
+then a new one will be created containing all the violations you have.
+The first time all violations will be reported.
+We do this to show the contents of the future baseline to the developer.
+Futher runs won't report any of the violations inside the baseline.
+
+If you already have ``.flake8-baseline.json`` file,
+than your baselined violations will be ignored.
+
+However, new violations will still be reported.
+
+Updating baseline
+~~~~~~~~~~~~~~~~~
+
+To update a baseline you can delete the old one:
+
+.. code:: bash
+
+  rm .flake8-baseline.json
+
+And create a new one with ``--baseline`` flag:
+
+.. code:: bash
+
+  flake8 --baseline your_project
+
+Baseline contents
+~~~~~~~~~~~~~~~~~
+
+Things we care when working with baselines:
+
+1. Violation codes and text descriptions
+2. Filenames
+
+When these values change
+(for example: file is renamed or violation code is changed),
+we will treat these violations as new ones.
+And report them to the user as usual.
+
+Things we don't care when working with baselines:
+
+1. Violation locations, because lines and columns
+   can be easily changed by simple refactoring
+2. Activated plugins
+3. Config values
+4. Target files and directories
+
+So, when you add new plugins or change any config values,
+then you might want ot update the baseline as well.
+
+
+Linting diffs
+-------------
+
 Existing legacy
 ~~~~~~~~~~~~~~~
 
@@ -119,7 +192,3 @@ And you are forced to improve things you write.
 
 At some point in time, you will have 100% perfect code.
 Good linters and constant refactoring is the key to the success.
-
-.. rubric:: Further reading
-
-- :ref:`Creating baselines for legacy projects <flakehell>`

docs/pages/usage/setup.rst

@@ -17,9 +17,8 @@ We also recommend to use `poetry <https://github.com/sdispater/poetry>`_
 instead of a default ``pip``.
 
 You might want to also install optional tools
-that pairs nicely with ``wemake-python-styleguide``:
+that pair nicely with ``wemake-python-styleguide``:
 
-- :ref:`flakehell` for easy integration into a **legacy** codebase
 - :ref:`nitpick` for sharing and validating
   configuration across multiple projects
 
@@ -41,15 +40,51 @@ See the ``flake8`` docs for `options <http://flake8.pycqa.org/en/latest/user/con
 and `usage examples <http://flake8.pycqa.org/en/latest/user/invocation.html>`_.
 
 Golden rule is to run your linter on each commit locally and inside the CI.
-And to fail the build if there are any style violations.
+And to fail the build if there are any violations.
 
 Check out how we do it in our different templates:
 
 - ``django`` and ``gitlab-ci``: https://github.com/wemake-services/wemake-django-template
 - ``python`` package and ``travis``: https://github.com/wemake-services/wemake-python-package
 
+
+Incremental adoption
+--------------------
+
+A very popular use-case is when you already
+have a relatively large codebase and want to addopt a new linter.
+
+Usually, it is a big pain: you have to spend a lot of time
+silencing tens or hundreds of violations.
+And you will end up with lots
+of silencing individual violations and refactoring.
+
+It is doable, but takes a lot of time.
+And makes the adoption of this linter pretty complicated.
+
+Let me introduce you ``--baseline`` option:
+
+.. code:: bash
+
+  flake8 --baseline your_project
+
+Here's what it does:
+
+1. When you run ``--baseline`` mode for the first time
+   it will report and record all the violations you have at the moment
+   into a new file called ``.flake8-baseline.json``
+
+2. If you try to run the same command once again, it will report no violations.
+   Why? Because all of them was saved as existing ones.
+   Now linter will report only new violations
+   that are not saved into the baseline.
+
+Done! Now you can integrate this linter
+into any codebase with just a single command!
+
+
 .. rubric:: Further reading
 
 - :ref:`Configuring and ignoring violations <configuration>`
-- :ref:`Intoducing this linter to a legacy codebase <flakehell>`
+- :ref:`Baseline usage <baseline>`
 - :ref:`Sharing configuration across multiple projects <nitpick>`