Merge a253f37 into 36ba28f

.gitignore

@@ -203,3 +203,6 @@ fabric.properties
 # Used for testing:
 ex.py
 setup.py
+
+# Usually you don't need to gitignore this file, but we use it for testing:
+/.flake8-baseline.json

.importlinter

@@ -13,6 +13,7 @@ containers =
 layers =
   checker
   formatter
+  patches
   transformations
   presets
   visitors
@@ -74,6 +75,7 @@ ignore_imports =
   # These modules must import from flake8 to provide required API:
   wemake_python_styleguide.checker -> flake8
   wemake_python_styleguide.formatter -> flake8
+  wemake_python_styleguide.patches.baseline -> flake8
   wemake_python_styleguide.options.config -> flake8
   # We disallow direct imports of our dependencies from anywhere, except:
   wemake_python_styleguide.formatter -> pygments

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,161 @@
 .. _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 our linter 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.
+
+Full baseline example
+~~~~~~~~~~~~~~~~~~~~~
+
+You start with a legacy file that looks like this:
+
+.. code:: python
+
+  # ex.py
+  x = 1
+
+Let's lint it and ignore existing errors!
+
+.. code:: bash
+
+  flake8 --baseline ex.py
+
+.. image:: https://raw.githubusercontent.com/wemake-services/wemake-python-styleguide/master/docs/_static/baseline-initial.png
+
+We are seeing our violation. Works as expected.
+Also, now your baseline is generated. Let's see that it works:
+
+.. code:: bash
+
+  cat .flake8-baseline.json
+
+.. image:: https://raw.githubusercontent.com/wemake-services/wemake-python-styleguide/master/docs/_static/baseline-contents.png
+
+Yes, here it is. It contains a single violation from your ``ex.py`` file.
+Let's run ``flake8`` again to see that no violations are going
+to be reported with a baseline:
+
+.. code:: bash
+
+  flake8 --baseline ex.py
+
+.. image:: https://raw.githubusercontent.com/wemake-services/wemake-python-styleguide/master/docs/_static/baseline-existing.png
+
+That works! No violations are reported.
+Because baseline covers all existing ones.
+Let's add some new ones to test that it will raise a violation:
+
+.. code:: python
+
+  # ex.py
+  x = 1
+  y = 1
+
+And run the linter:
+
+.. code:: bash
+
+  flake8 --baseline ex.py
+
+.. image:: https://raw.githubusercontent.com/wemake-services/wemake-python-styleguide/master/docs/_static/baseline-new-violations.png
+
+And yes, new violation is reported! It works just as we planned.
+Enjoy your incremental adoption!
+
+
+Linting diffs
+-------------
+
 Existing legacy
 ~~~~~~~~~~~~~~~
 
@@ -119,7 +250,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>`