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