Users who have contributed to this file

Contributing to Flake8

There are many ways to contribute to |Flake8|, and we encourage them all:

contributing bug reports and feature requests

contributing documentation (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.

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.

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.

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:

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 read 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, its 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. This provides
direction for other contributors about when an issue or merge request will be
delivered.