From 822b7905183061050d1badfa15cb1290fb22b942 Mon Sep 17 00:00:00 2001
From: sobolevn
Date: Tue, 24 Mar 2020 13:49:35 +0300
Subject: [PATCH] Adds --baseline docs
---
CHANGELOG.md | 4 +-
README.md | 18 ++--
docs/pages/usage/integrations/flakehell.rst | 89 -------------------
docs/pages/usage/integrations/index.rst | 3 +-
docs/pages/usage/integrations/legacy.rst | 93 +++++++++++++++++---
docs/pages/usage/setup.rst | 43 ++++++++-
styles/flakehell.toml | 33 -------
wemake_python_styleguide/patches/baseline.py | 64 --------------
8 files changed, 135 insertions(+), 212 deletions(-)
delete mode 100644 docs/pages/usage/integrations/flakehell.rst
delete mode 100644 styles/flakehell.toml
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1a0a5671b..47f33dff8 100644
--- a/CHANGELOG.md
+++ b/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
diff --git a/README.md b/README.md
index fe34b456a..caab1de9c 100644
--- a/README.md
+++ b/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">
+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.
diff --git a/docs/pages/usage/integrations/flakehell.rst b/docs/pages/usage/integrations/flakehell.rst
deleted file mode 100644
index 009e65ed4..000000000
--- a/docs/pages/usage/integrations/flakehell.rst
+++ /dev/null
@@ -1,89 +0,0 @@
-.. _flakehell:
-
-flakehell
----------
-
-``flakehell`` is a `legacy-first `_
-wrapper around ``flake8`` linter to make it awesome.
-
-.. image:: https://raw.githubusercontent.com/life4/flakehell/master/assets/logo.png
-
-What does it mean? It means, that it adds some useful
-features to the core ``flake8`` with the new command line utility:
-
-.. code:: bash
-
- pip install flakehell # however we recommend to use `poetry`
-
-Then you will have to configure ``flakehell`` inside your ``pyproject.toml``:
-
-- You can run ``flakehell plugins`` to see what plugins are you missing
- and configure it properly
-- Or you can use our `preset `_
- as ``base`` configuration like so:
-
- .. code:: toml
-
- [tool.flakehell]
- # optionally inherit from remote config (or local if you want)
- base = "https://github.com/wemake-services/wemake-python-styleguide/blob/master/styles/flakehell.toml"
-
-And then:
-
-.. code:: bash
-
- flakehell lint # accepts the same arguments, does the same as `flake8`
-
-The most exciting feature for us is ``baseline`` generation.
-
-.. _flakehell-legacy:
-
-Legacy first
-~~~~~~~~~~~~
-
-When you project is old you cannot just install and use a new linter.
-Since your codebase will contain hundreds or even thousands of violations.
-
-Some of them can be auto-formatted, some of them can be silenced.
-But, what if there are still too many of them to fix right here and right now?
-
-Let me introduce the ``baseline`` concept:
-
-1. The first step is to create a ``baseline`` via:
-
- .. code:: bash
-
- flakehell baseline > .flakehell_baseline
-
- It will contain all your current violations list
- with exact locations and quantity.
-2. Then specify the ``baseline`` in the configuration:
-
- .. code:: ini
-
- # Inside your pyproject.toml
- [tool.flakehell]
- baseline = ".flakehell_baseline"
-
-3. Run your linter again with ``flakehell lint``. You will see no violations!
-4. Try to add a new one into your source code.
- And run your linter again. It will be reported!
-
-The ``baseline`` method allows you to report any new violations
-and fix the old ones little by little.
-So, the integration is almost painless.
-
-That's why we call it "legacy-first".
-Enjoy your new linter in your old project!
-
-Support
-~~~~~~~
-
-``flakehell`` is officially supported by ``wemake-python-styleguide``
-and developed by the same people.
-
-Further reading
-~~~~~~~~~~~~~~~
-
-- Our :ref:`legacy` guide
-- Official docs: `flakehell.readthedocs.io `_
diff --git a/docs/pages/usage/integrations/index.rst b/docs/pages/usage/integrations/index.rst
index 75c5b50fc..d730f32a8 100644
--- a/docs/pages/usage/integrations/index.rst
+++ b/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
diff --git a/docs/pages/usage/integrations/legacy.rst b/docs/pages/usage/integrations/legacy.rst
index cc9b57957..55e7068b1 100644
--- a/docs/pages/usage/integrations/legacy.rst
+++ b/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 `_: always leave
+4. Use `boyscout 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 `
diff --git a/docs/pages/usage/setup.rst b/docs/pages/usage/setup.rst
index 08943f5cf..4c4e1cf3d 100644
--- a/docs/pages/usage/setup.rst
+++ b/docs/pages/usage/setup.rst
@@ -17,9 +17,8 @@ We also recommend to use `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 `_.
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 `
-- :ref:`Intoducing this linter to a legacy codebase `
+- :ref:`Baseline usage `
- :ref:`Sharing configuration across multiple projects `
diff --git a/styles/flakehell.toml b/styles/flakehell.toml
deleted file mode 100644
index 9903d1046..000000000
--- a/styles/flakehell.toml
+++ /dev/null
@@ -1,33 +0,0 @@
-# `flakehell` specific configuration.
-# This file is served as `base` config under `[tool.flakehell]`
-
-# Make sure to install it with:
-# `pip install flakehell`
-
-# See:
-# https://wemake-python-stylegui.de/en/latest/pages/usage/integrations/flakehell.html
-
-# This file is not related to `nitpick` at all.
-# This file is optional, not required for `flake8` users.
-
-[tool.flakehell]
-format = "grouped"
-show_source = true
-statistics = false
-doctests = true
-enable_extensions = "G"
-
-accept_encodings = "utf-8"
-max_complexity = 6
-max_line_length = 80
-
-ignore = "D100, D104, D401, W504, RST303, RST304, DAR103, DAR203"
-
-[tool.flakehell.plugins]
-"flake8-*" = ["+*"]
-mccabe = ["+*"]
-nitpick = ["+*"]
-"pep8-naming" = ["+*"]
-pycodestyle = ["+*"]
-pyflakes = ["+*"]
-"wemake-python-styleguide" = ["+*"]
diff --git a/wemake_python_styleguide/patches/baseline.py b/wemake_python_styleguide/patches/baseline.py
index 128b813af..290ca9508 100644
--- a/wemake_python_styleguide/patches/baseline.py
+++ b/wemake_python_styleguide/patches/baseline.py
@@ -1,67 +1,3 @@
-"""
-Baselines allow us to adopt this linter incrementally.
-
-You can start using it with just a single command!
-
-.. code:: bash
-
- flake8 --baseline your_module
-
-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.
-
-If you already have ``.flake8-baseline.json`` file,
-than your pre-saved 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.
-
-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.
-
-"""
-
from collections import defaultdict
from typing import Iterable, Tuple, Type