contributing.rst 6.37 KB
Newer Older
1 2 3 4
========================
 Contributing to Flake8
========================

5
There are many ways to contribute to |Flake8|, and we encourage them all:
6 7 8

- contributing bug reports and feature requests

Ville Skyttä's avatar
Ville Skyttä committed
9
- contributing documentation (and yes that includes this document)
10 11 12 13

- reviewing and triaging bugs and merge requests

Before you go any further, please allow me to reassure you that I do want
14
*your* contribution. If you think your contribution might not be valuable, I
15 16 17 18 19 20
reassure you that any help you can provide *is* valuable.


Code of Conduct
===============

21
|Flake8| adheres to the `Python Code Quality Authority's Code of Conduct`_.
22 23
Any violations of the Code of Conduct should be reported to Ian Stapleton
Cordasco (graffatcolmingov [at] gmail [dot] com).
24 25 26 27 28


Setting Up A Development Environment
====================================

29
To contribute to |Flake8|'s development, you simply need:
30 31 32 33

- Python (one of the versions we support)

- `tox`_
34

35 36 37 38 39 40 41 42 43 44 45 46
  We suggest installing this like:

  .. prompt:: bash

        pip install --user tox

  Or

  .. prompt:: bash

        python<version> -m pip install --user tox

47
- your favorite editor
48 49 50 51 52


Filing a Bug
============

53 54 55 56 57
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
58 59 60 61 62 63
check.

**Please search for closed and open bug reports before opening new ones.**

All bug reports about checks should go to their respective projects:

64
- Error codes starting with ``E`` and ``W`` should be reported to
65 66
  `pycodestyle`_.

67
- Error codes starting with ``F`` should be reported to `pyflakes`_
68

69
- Error codes starting with ``C`` should be reported to `mccabe`_
70 71 72 73 74


Requesting a New Feature
========================

75
When requesting a new feature in |Flake8|, please fill out the issue template.
76 77 78 79 80 81 82 83
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:

84 85
    I need |Flake8| to frobulate these files because my team expects them to
    frobulated but |Flake8| currently does not frobulate them. We tried using
86 87 88 89 90 91 92 93 94
    ``--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
==========================

95
To contribute to |Flake8|'s documentation, you might want to first read a
96 97 98 99
little about reStructuredText or Sphinx. |Flake8| has a :ref:`guide of best
practices <docs-style>` when contributing to our documentation. For the most
part, you should be fine following the structure and style of the rest of
|Flake8|'s documentation.
100

101
All of |Flake8|'s documentation is written in reStructuredText and rendered by
102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133
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
=================

134
|Flake8| development happens on `GitLab`_. Code contributions should be
135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165
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.

166 167
- Follow the guidelines in :ref:`writing-code`

168 169 170 171 172 173 174 175 176 177 178
- Avoid having :code:`.gitignore` file in your PR

  Changes to :code:`.gitignore` will rarely be accepted.

  If you need to add files to :code:`.gitignore` you have multiple options

  - Create a global :code:`.gitignore` file
  - Create/update :code:`.git/info/exclude` file.

  Both these options are explained in detail `here <https://help.github.com/en/articles/ignoring-files#create-a-global-gitignore>`_

179 180 181 182 183

Reviewing and Triaging Issues and Merge Requests
================================================

When reviewing other people's merge requests and issues, please be
184
**especially** mindful of how the words you choose can be read by someone
185 186
else. We strive for professional code reviews that do not insult the
contributor's intelligence or impugn their character. The code review
tim smith's avatar
tim smith committed
187
should be focused on the code, its effectiveness, and whether it is
188
appropriate for |Flake8|.
189 190 191 192

If you have the ability to edit an issue or merge request's labels, please do
so to make search and prioritization easier.

193
|Flake8| uses milestones with both issues and merge requests. This provides
194
direction for other contributors about when an issue or merge request will be
195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215
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