Add contributing documentation

docs/source/internal/contributing.rst

@@ -0,0 +1,200 @@
+========================
+ Contributing to Flake8
+========================
+
+We encourage multiple methods of participation in Flake8:
+
+- contributing bug reports and feature requests
+
+- contributing documenation (and yes that includes this document)
+
+- reviewing and triaging bugs and merge requests
+
+Before you go any further, please allow me to reassure you that I do want
+*your* contribution. If you think your contribution might not be valuable, I 
+reassure you that any help you can provide *is* valuable.
+
+
+Code of Conduct
+===============
+
+Flake8 adheres to the `Python Code Quality Authority's Code of Conduct`_.
+Any violations of the Code of Conduct should be reported to Ian Cordasco
+(graffatcolmingov [at] gmail [dot] com).
+
+
+Setting Up A Development Environment
+====================================
+
+To contribute to Flake8's development, you simply need:
+
+- Python (one of the versions we support)
+
+- `tox`_
+  
+  We suggest installing this like:
+
+  .. prompt:: bash
+
+        pip install --user tox
+
+  Or
+
+  .. prompt:: bash
+
+        python<version> -m pip install --user tox
+
+- and your favorite editor
+
+
+Filing a Bug
+============
+
+When filing a bug against Flake8, please fill out the issue template as it is
+provided to you by `GitLab`_. If your bug is in reference to one of the
+checks that Flake8 reports by default, please do not report them to Flake8
+unless Flake8 is doing something to prevent the check from running or you
+have some reason to believe Flake8 is inhibiting the effectiveness of the
+check.
+
+**Please search for closed and open bug reports before opening new ones.**
+
+All bug reports about checks should go to their respective projects:
+
+- Check codes starting with ``E`` and ``W`` should be reported to
+  `pycodestyle`_.
+
+- Check codes starting with ``F`` should be reported to `pyflakes`_
+
+- Check codes starting with ``C`` should be reported to `mccabe`_
+
+
+Requesting a New Feature
+========================
+
+When requesting a new feature in Flake8, please fill out the issue template.
+Please also note if there are any existing alternatives to your new feature
+either via plugins, or combining command-line options. Please provide example
+use cases. For example, do not ask for a feature like this:
+
+    I need feature frobulate for my job.
+
+Instead ask:
+
+    I need Flake8 to frobulate these files because my team expects them to
+    frobulated but Flake8 currently does not frobulate them. We tried using
+    ``--filename`` but we could not create a pattern that worked.
+
+The more you explain about *why* you need a feature, the more likely we are to
+understand your needs and help you to the best of our ability.
+
+
+Contributing Documentation
+==========================
+
+To contribute to Flake8's documentation, you should first familiarize yourself
+with reStructuredText and Sphinx. For the most part, you should be fine
+following the structure and style of the rest of Flake8's documentation.
+
+All of Flake8's documentation is written in reStructuredText and rendered by
+Sphinx. The source (reStructuredText) lives in ``docs/source/``. To build
+the documentation the way our Continuous Integration does, run:
+
+.. prompt:: bash
+
+    tox -e docs
+
+To view the documentation locally, you can also run:
+
+.. prompt:: bash
+
+    tox -e serve-docs
+
+You can run the latter in a separate terminal and continuously re-run the
+documentation generation and refresh the documentation you're working on.
+
+.. note::
+
+    We lint our documentation just like we lint our code.
+    You should also run:
+
+    .. prompt:: bash
+
+        tox -e linters
+
+    After making changes and before pushing them to ensure that they will
+    pass our CI tests.
+
+
+Contributing Code
+=================
+
+Flake8 development happens on `GitLab`_. Code contributions should be 
+submitted there.
+
+Merge requests should:
+
+- Fix one issue and fix it well
+
+  Fix the issue, but do not include extraneous refactoring or code
+  reformatting. In other words, keep the diff short, but only as short
+  as is necessary to fix the bug appropriately and add sufficient testing
+  around it. Long diffs are fine, so long as everything that it includes
+  is necessary to the purpose of the merge request.
+
+- Have descriptive titles and descriptions
+
+  Searching old merge requests is made easier when a merge request is well
+  described.
+
+- Have commits that follow this style:
+
+  .. code::
+
+        Create a short title that is 50 characters long
+
+        Ensure the title and commit message use the imperative voice. The
+        commit and you are doing something. Also, please ensure that the
+        body of the commit message does not exceed 72 characters.
+
+        The body may have multiple paragraphs as necessary.
+
+        The final line of the body references the issue appropriately.
+
+
+Reviewing and Triaging Issues and Merge Requests
+================================================
+
+When reviewing other people's merge requests and issues, please be
+**especially** mindful of how the words you choose can be ready by someone
+else. We strive for professional code reviews that do not insult the
+contributor's intelligence or impugn their character. The code review
+should be focused on the code, it's effectiveness, and whether it is
+appropriate for Flake8.
+
+If you have the ability to edit an issue or merge request's labels, please do
+so to make search and prioritization easier.
+
+Flake8 uses milestones with both issues and merge requests to provide
+other contributors direction about when an issue or merge request will be
+delivered.
+
+
+.. links
+.. _Python Code Quality Authority's Code of Conduct:
+    http://meta.pycqa.org/en/latest/code-of-conduct.html
+
+.. _tox:
+    https://tox.readthedocs.io/
+
+.. _GitLab:
+    https://gitlab.com/pycqa/flake8
+
+.. _pycodestyle:
+    https://github.com/pycqa/pycodestyle
+
+.. _pyflakes:
+    https://github.com/pyflakes/pyflakes
+
+.. _mccabe:
+    https://github.com/pycqa/mccabe

docs/source/internal/index.rst

@@ -15,6 +15,7 @@ pull gently.
 .. toctree::
     :maxdepth: 2
 
+    contributing
     checker
     cli
     formatters