From eb29f117386641fdc0bca2c3833ec14fea0a5751 Mon Sep 17 00:00:00 2001
From: Ian Cordasco <graffatcolmingov@gmail.com>
Date: Sun, 6 Dec 2015 13:36:01 -0600
Subject: [PATCH] Flesh out some portions of the design goals

---
 DESIGN.rst | 79 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)

diff --git a/DESIGN.rst b/DESIGN.rst
index 6f40e51..dee98ee 100644
--- a/DESIGN.rst
+++ b/DESIGN.rst
@@ -11,8 +11,12 @@ Outline
 
    #. :ref:`autofixing`
 
+   #. :ref:`reporter-plugins`
+
    #. :ref:`options-passing`
 
+   #. :ref:`plugin-default-ignore`
+
 #. :ref:`options`
 
    #. :ref:`better-select-ignore`
@@ -30,31 +34,106 @@ Outline
 Better Plugins Support
 ----------------------
 
+Currently, Flake8 has some rather excellent support for plugins. It currently
+allows for the following:
+
+- Third-party packages to register checks
+
+- Checks to be disabled by default
+
+- Checks to accept an AST compiled tree, physical lines, or logical lines.
+
+- Flake8 handles running those checks in separate subprocesses as necessary
+
+That said, plugins cannot access the options passed on the command-line, or
+options parsed from config files (without parsing them, themselves) and all
+reporting is handled by pep8 instead of flake8 which reduces the flexibility
+users have in aggregating reports.
+
 .. _checking:
 
 Support for Plugins that Only Run Checks
 ++++++++++++++++++++++++++++++++++++++++
 
+Flake8 currently already supports plugins that only run checks. This support
+needs to continue and should be trivial to continue.
+
 .. _autofixing:
 
 Support for Plugins that Autofix Errors
 +++++++++++++++++++++++++++++++++++++++
 
+Flake8 should enable people writing plugins for both core Flake8 checkers and
+third-party checkers that allow the code to be automatically fixed. The trick
+is in how to do this.
+
+Once Flake8 has control over running plugins and treats pep8, flake8, and
+mccabe as "plugins", it will aggregate the errors returned by all of the
+plugins and be able to "notify" other plugins that have chosen to listen for
+errors so those plugins can auto-fix the problems in the file.
+
+See https://gitlab.com/pycqa/flake8/issues/84
+
+.. _reporter-plugins:
+
+Support for Plugins that Format Output
+++++++++++++++++++++++++++++++++++++++
+
+Flake8 currently supports formatting output via pep8's ``--format`` option.
+This works but is fundamentally a bit limiting. Allowing users to replace or
+compose formatters would allow for certain formatters to highlight more
+important information over less important information as the user deems
+necessary.
+
+See https://gitlab.com/pycqa/flake8/issues/66
+
 .. _options-passing:
 
 Support for Plugins Require Parsed Options
 ++++++++++++++++++++++++++++++++++++++++++
 
+Plugins currently are able to use ``add_options`` and ``parse_options``
+classmethods to register and retrieve options information. This is admittedly
+a little awkward and could be improved, but should at least be preserved in
+this rewrite.
+
+See potential improvements as a result of
+https://gitlab.com/pycqa/flake8/issues/88
+
+.. _plugin-default-ignore:
+
+Support for Plugins Specifying Default Ignore list
+++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Plugins currently have no way of extending the default ignore list. This means
+they have to hard-code checks to auto-ignore errors.
+
 .. _options:
 
 Better Options Support
 ----------------------
 
+Currently there are some options handled by pep8 that are handled poorly.
+Further, the way the options work is confusing to some, e.g., when specifying
+``--ignore``, users do not expect it to override the ``DEFAULT_IGNORE`` list.
+Users also don't expect ``--ignore`` and ``--select`` to step on each other's
+toes.
+
 .. _better-select-ignore:
 
 Support for Better Select/Ignore Handling
 +++++++++++++++++++++++++++++++++++++++++
 
+Currently ``--select`` and ``--ignore`` cause one or the other to be ignored.
+Users presently cannot specify both for granularity. This should be
+significantly improved.
+
+Further, new tools have developed ``--add-select`` and ``--add-ignore`` which
+allows an add-only interface. This seems to be a good direction to follow.
+Flake8 should support this.
+
+See https://github.com/PyCQA/pep8/issues/390
+
 .. _standard-in:
 
 Better stdin support