1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
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
134
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
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
|
========================
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.
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 Stapleton
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
- 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 `GitHub`_. 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:
- Error codes starting with ``E`` and ``W`` should be reported to
`pycodestyle`_.
- Error codes starting with ``F`` should be reported to `pyflakes`_
- Error 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 might want to first read a
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.
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 `GitHub`_. 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.
- Follow the guidelines in :ref:`writing-code`
- 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>`_
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.
.. links
.. _Python Code Quality Authority's Code of Conduct:
http://meta.pycqa.org/en/latest/code-of-conduct.html
.. _tox:
https://tox.readthedocs.io/
.. _GitHub:
https://github.com/pycqa/flake8
.. _pycodestyle:
https://github.com/pycqa/pycodestyle
.. _pyflakes:
https://github.com/pyflakes/pyflakes
.. _mccabe:
https://github.com/pycqa/mccabe
|
