Skip to content

Commit 7b30463

Browse files
casperdclcasperdcl
committed
much doc clean such happy
1 parent f492111 commit 7b30463

3 files changed

Lines changed: 214 additions & 197 deletions

File tree

‎CONTRIBUTE‎

Lines changed: 211 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,47 @@
11
HOW TO CONTRIBUTE TO TQDM
22
=========================
33

4-
This file describes how to contribute changes to the project, and how to
5-
upload to the pypi repository.
4+
This file describes how to
5+
6+
- contribute changes to the project, and
7+
- upload released to the pypi repository.
68

79
Most of the management commands have been directly placed inside the
8-
Makefile: `python setup.py make [alias]`, (or simply `make [alias]` in
9-
UNIX-like environments).
10+
Makefile:
11+
12+
```
13+
make [<alias>] # on UNIX-like environments
14+
python setup.py make [<alias>] # if make is unavailable
15+
```
1016

11-
Note: to use the Makefile on Windows, you need to install make.exe,
12-
for example by installing [MinGW MSYS](http://www.mingw.org/wiki/msys).
17+
Use the alias `help` (or leave blank) to list all available aliases.
1318

1419

15-
HOW TO COMMIT YOUR CONTRIBUTIONS
16-
--------------------------------
20+
HOW TO COMMIT CONTRIBUTIONS
21+
---------------------------
1722

1823
Contributions to the project are made using the "Fork & Pull" model. The
1924
typical steps would be:
2025

21-
- create an account on [github](https://github.com)
22-
- fork [tqdm](https://github.com/tqdm/tqdm)
23-
- make a local clone: `git clone https://github.com/your_account/tqdm.git`
24-
- make your changes on your local copy
25-
- commit your changes `git commit -a -m "my message"`
26-
- TEST YOUR CHANGES (see below)
27-
- `push` to your github account: `git push origin`
28-
- finally, create a Pull Request (PR) from your github fork
26+
1. create an account on [github](https://github.com)
27+
2. fork [tqdm](https://github.com/tqdm/tqdm)
28+
3. make a local clone: `git clone https://github.com/your_account/tqdm.git`
29+
4. make changes on the local copy
30+
5. test (see below) and commit changes `git commit -a -m "my message"`
31+
6. `push` to your github account: `git push origin`
32+
7. create a Pull Request (PR) from your github fork
2933
(go to your fork's webpage and click on "Pull Request."
3034
You can then add a message to describe your proposal.)
3135

3236

3337
TESTING
3438
-------
3539

36-
To test functionality on your machine (such as before submitting a Pull
40+
To test functionality (such as before submitting a Pull
3741
Request), there are a number of unit tests.
3842

39-
40-
Standard unit testing
41-
~~~~~~~~~~~~~~~~~~~~~
43+
Standard unit tests
44+
~~~~~~~~~~~~~~~~~~~
4245

4346
The standard way to run the tests:
4447

@@ -47,18 +50,8 @@ The standard way to run the tests:
4750
- run the following command:
4851

4952
```
50-
python setup.py make test
51-
```
52-
53-
or
54-
55-
```
56-
make test
57-
```
58-
59-
or
60-
61-
```
53+
[python setup.py] make test
54+
# or:
6255
tox --skip-missing-interpreters
6356
```
6457

@@ -73,22 +66,201 @@ you can use `MiniConda` to install a minimal setup. You must also make sure
7366
that each distribution has an alias to call the Python interpreter:
7467
`python27` for Python 2.7's interpreter, `python32` for Python 3.2's, etc.
7568

76-
77-
Alternative unit testing with Nose
69+
Alternative unit tests with Nose
7870
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7971

80-
Alternatively, use `nose` to run the tests just for your Python version:
72+
Alternatively, use `nose` to run the tests just for the current Python version:
8173

8274
- install `nose` and `flake8`
8375
- run the following command:
8476

8577
```
86-
python setup.py make alltests
78+
[python setup.py] make alltests
8779
```
8880

89-
or
81+
82+
83+
MANAGE A NEW RELEASE
84+
=====================
85+
86+
This section is intended for the project's maintainers and describes
87+
how to build and upload a new release. Once again,
88+
`[python setup.py] make [<alias>]` will help.
89+
90+
91+
SEMANTIC VERSIONING
92+
-------------------
93+
94+
The tqdm repository managers should:
95+
96+
- regularly bump the version number in the file
97+
[_version.py](https://raw.githubusercontent.com/tqdm/tqdm/master/tqdm/_version.py)
98+
- follow the [Semantic Versioning](http://semver.org/) convention
99+
- take care of this (instead of users) to avoid PR conflicts
100+
solely due to the version file bumping
101+
102+
Note: tools can be used to automate this process, such as
103+
[bumpversion](https://github.com/peritus/bumpversion) or
104+
[python-semanticversion](https://github.com/rbarrois/python-semanticversion/).
105+
106+
107+
CHECKING SETUP.PY
108+
-----------------
109+
110+
To check that the `setup.py` file is compliant with PyPi requirements (e.g.
111+
version number; reStructuredText in README.rst) use:
112+
113+
```
114+
[python setup.py] make testsetup
115+
```
116+
117+
To upload just metadata (including overwriting mistakenly uploaded metadata)
118+
to PyPi, use:
119+
120+
```
121+
[python setup.py] make pypimeta
122+
```
123+
124+
125+
MERGING PULL REQUESTS
126+
---------------------
127+
128+
This section describes how to cleanly merge PRs.
129+
130+
1 Rebase
131+
~~~~~~~~
132+
133+
From your project repository, merge and test
134+
(replace `pr-branch-name` as appropriate):
90135

91136
```
92-
nosetests --with-coverage --cover-package=tqdm -v tqdm/
93-
python -m flake8 tqdm/_tqdm.py
137+
git fetch origin
138+
git checkout -b pr-branch-name origin/pr-branch-name
139+
git rebase master
140+
```
141+
142+
If there are conflicts:
143+
144+
```
145+
git mergetool
146+
git rebase --continue
147+
```
148+
149+
2 Push
150+
~~~~~~
151+
152+
Update branch with the rebased history:
153+
94154
```
155+
git push origin pr-branch-name --force
156+
```
157+
158+
Non maintainers can stop here.
159+
160+
Note: NEVER just `git push --force` (this will push all local branches,
161+
overwriting remotes).
162+
163+
3 Merge
164+
~~~~~~~
165+
166+
```
167+
git checkout master
168+
git merge --no-ff pr-branch-name
169+
```
170+
171+
4 Test
172+
~~~~~~
173+
174+
```
175+
[python setup.py] make alltests
176+
```
177+
178+
5 Version
179+
~~~~~~~~~
180+
181+
Modify tqdm/_version.py and ammend the last (merge) commit:
182+
183+
```
184+
git add tqdm/_version.py
185+
git commit --amend # Add "+ bump version" in the commit message
186+
```
187+
188+
6 Push to master
189+
~~~~~~~~~~~~~~~~
190+
191+
```
192+
git push origin master
193+
```
194+
195+
196+
BUILDING A RELEASE AND UPLOADING TO PYPI
197+
----------------------------------------
198+
199+
Formally publishing requires additional steps: testing and tagging.
200+
201+
Test
202+
~~~~
203+
204+
- ensure that all online CI tests have passed
205+
- check `setup.py` and `MANIFEST.in` - which define the packaging
206+
process and info that will be uploaded to [pypi](pypi.python.org) -
207+
using `[python setup.py] make installdev`
208+
209+
Tag
210+
~~~
211+
212+
- ensure the version has been bumped, committed **and** tagged.
213+
The tag format is `v{major}.{minor}.{patch}`, for example: `v4.4.1`.
214+
The current commit's tag is used in the version checking process.
215+
If the current commit is not tagged appropriately, the version will
216+
display as `v{major}.{minor}.{patch}-{commit_hash}`.
217+
218+
Upload
219+
~~~~~~
220+
221+
Build tqdm into a distributable python package:
222+
223+
```
224+
[python setup.py] make build
225+
```
226+
227+
This will generate several builds in the `dist/` folder. On non-windows
228+
machines the windows `exe` installer may fail to build. This is normal.
229+
230+
Finally, upload everything to pypi. This can be done easily using the
231+
[twine](https://github.com/pypa/twine) module:
232+
233+
```
234+
[python setup.py] make pypi
235+
```
236+
237+
Also, the new release can (should) be added to `github` by creating a new
238+
release from the web interface; uploading packages from the `dist/` folder
239+
created by `[python setup.py] make build`.
240+
241+
Notes
242+
~~~~~
243+
244+
- you can also test on the pypi test servers `testpypi.python.org/pypi`
245+
before the real deployment
246+
- in case of a mistake, you can delete an uploaded release on pypi, but you
247+
cannot re-upload another with the same version number
248+
- in case of a mistake in the metadata on pypi (e.g. bad README),
249+
updating just the metadata is possible: `[python setup.py] make pypimeta`
250+
251+
252+
QUICK DEV SUMMARY
253+
-----------------
254+
255+
For expereinced devs, once happy with local master:
256+
257+
1. bump version in `tqdm/_version.py`
258+
2. test (`[python setup.py] make alltests`)
259+
3. `git commit [--amend] # -m "bump version"`
260+
4. `git push`
261+
5. wait for tests to pass
262+
a) in case of failure, fix and go back to (2)
263+
6. `git tag vM.m.p && git push --tags`
264+
7. `[python setup.py] make distclean`
265+
8. `[python setup.py] make build`
266+
9. `[python setup.py] make pypi`

‎Makefile‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,9 @@
3434
pypi
3535
none
3636

37+
help:
38+
@python setup.py make
39+
3740
alltests:
3841
@+make testcoverage
3942
@+make testperf

0 commit comments

Comments
 (0)