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
|
Contributing to this project
============================
Checklist
---------
#. All potential contributors must read the :ref:`code-of-conduct` and follow
it
#. Fork the repository on `GitHub`_ or `GitLab`_
#. Create a new branch, e.g., ``git checkout -b bug/12345``
#. Fix the bug and add tests (if applicable [#]_, see :ref:`how-to-add-tests`)
#. Run the tests (see :ref:`how-to-run-tests` below)
#. Add documentation (as necessary) for your change
#. Build the documentation to check for errors and formatting (see
:ref:`how-to-build-the-docs` below)
#. Add yourself to the :file:`AUTHORS.rst` (unless you're already there)
#. Commit it. Follow these rules in your commit message:
* Keep the subject line under 50 characters
* Use an imperative verb to start the commit
* Use an empty line between the subject and the message
* Describe the *why* in detail in the message portion of the commit
* Wrap the lines of the message at 72 characters
* Add the appropriate "Closes #12345" syntax to autoclose the issue it
fixed (if it closes an issue)
* See :ref:`example-commit-message` below
#. Push it to your fork
#. Create a request for us to merge your contribution
After this last step, it is possible that we may leave feedback in the form of
review comments. When addressing these comments, you can follow two
strategies:
* Amend/rebase your changes into an existing commit
* Create a new commit with a different message [#]_ describing the changes in
that commit and push it to your branch
This project is not opinionated about which approach you should prefer. We
only ask that you are aware of the following:
* Neither GitHub nor GitLab notifies us that you have pushed new changes. A
friendly ping is encouraged
* If you continue to use the same branch that you created the request from,
both GitHub and GitLab will update the request on the website. You do
**not** need to create a new request for the new changes.
.. _code-of-conduct:
.. include:: ../CODE_OF_CONDUCT.rst
.. _how-to-add-tests:
How To Add Tests
----------------
We use `pytest`_ to run tests and to simplify how we write tests. If you're
fixing a bug in an existing please find tests for that module or feature and
add to them. Most tests live in the ``tests`` directory. If you're adding a
new feature in a new submodule, please create a new module of test code. For
example, if you're adding a submodule named ``foo`` then you would create
``tests/test_foo.py`` which will contain the tests for the ``foo`` submodule.
.. _how-to-run-tests:
How To Run The Tests
--------------------
Run the tests in this project using `tox`_. Before you run the tests, ensure
you have installed tox either using your system package manager (e.g., apt,
yum, etc.), or your prefered python installer (e.g., pip).
Then run the tests on at least Python 2.7 and Python 3.x, e.g.,
.. code::
$ tox -e py27,py34
Finally run one, or both, of the flake8 style enforcers, e.g.,
.. code::
$ tox -e py27-flake8
# or
$ tox -e py34-flake8
It is preferable if you run both to catch syntax errors that might occur in
Python 2 or Python 3 (based on how familiar you are with the common subset of
language from both).
Tox will manage virtual environments and dependencies for you so it will be
the only dependency you need to install to contribute to this project.
.. _how-to-build-the-docs:
How To Build The Documentation
------------------------------
To build the docs, you need to ensure tox is installed and then you may run
.. code::
$ tox -e docs
This will build the documentation into ``docs/_build/html``. If you then run
.. code::
$ python2.7 -m SimpleHTTPServer
# or
$ python3.4 -m http.server
from that directory, you can view the docs locally at http://localhost:8000/.
.. _example-commit-message:
Example Commit Message
----------------------
::
Allow users to use the frob when uploading data
When uploading data with FooBar, users may need to use the frob method
to ensure that pieces of data are not munged.
Closes #1234567
Footnotes
---------
.. [#] You might not need tests if you're updating documentation, fixing a
typo, or updating a docstring. If you're fixing a bug, please add
tests.
.. [#] If each commit has the same message, the reviewer may ask you to
squash your commits or may squash them for you and perform a manual
merge.
.. _GitHub: https://github.com/requests/toolbelt
.. _GitLab: https://gitlab.com/sigmavirus24/toolbelt
.. _tox: https://tox.readthedocs.io/
.. _pytest: https://docs.pytest.org/
|
