tqdm/CONTRIBUTE

HOW TO CONTRIBUTE TO TQDM
===========================

This file describes how to contribute changes to the project, and how to 
upload to the pypi repository. 


HOW TO COMMIT YOUR CONTRIBUTIONS 
----------------------------------------------------------- 

Contributions to the project is made using the `Fork & Pull` model. 
Here's a quickstart on how to do that (your mileage may vary depending 
on your git config): 

- first create an account on github.
- then go on the tqdm page `https://github.com/tqdm/tqdm` and fork it
(click on the fork button).
- now make a local clone of the project:
`git clone https://github.com/your_account/tqdm.git`
- do your changes on your local copy.
- commit your changes `git commit -m "my message"`
- TEST YOUR CHANGES (see below).
- push to your github account `git push origin`
- and now you can make a `Pull Request` from your github fork by 
going to the webpage and clicking on `Pull Request`. You can then add a 
message to describe your proposal.
- Your changes will then be reviewed and integrated into the project if OK. 


TESTING
------------- 

Before submitting a Pull Request, you need to make sure that all the 
unit tests pass. This will ensure that your changes did not introduce 
any regression in the features that already working. 

To run the test, cd to the root of the tqdm folder (in the same folder 
as this file), and then type the following (you need to install `tox`):

```
make test
make coverage
make flake8
```

Alternatively, if you can't use the Makefile, you can use the following to run
the tests (you need to install the `nosetest` python module before):

```
nosetests --with-coverage --cover-package=tqdm -v tqdm/
python -m flake8 tqdm/_tqdm.py
```

If all the tests pass, then everything's good, you can submit a Pull Request.


SEMANTIC VERSIONING
---------------------------------- 

The tqdm repository managers should regularly bump the version number in 
the VERSION file to follow the [Semantic Versioning](http://semver.org/) 
convention. 

Tools can be used to automate this process, such as 
[bumpversion](https://github.com/peritus/bumpversion) or 
[python-semanticversion](https://github.com/rbarrois/python-semanticvers 
ion/) to automate this task. 

The managers should take care of this instead of users to avoid PR 
conflicts solely due to the VERSION file bumping. 


BUILDING A RELEASE AND UPLOADING TO PYPI
---------------------------------------------------------------------

First, we need to check the setup.py and MANIFEST.in files, which define 
the packaging process and the infos that will be uploaded to pypi. 

You can check the result easily by using the following commands: 

```
python setup.py develop --uninstall
python setup.py develop
``` 

Secondly, we need to build tqdm into a distributable python package: 

```
python setup.py sdist --formats=gztar,zip bdist_wininst --plat-name=win32
python setup.py sdist bdist_wheel --plat-name=win32
``` 

This will generate several builds in the dist/ folder. 

Finally, we can upload everything to pypi. Uploading to pypi can be done 
easily using the [twine](https://github.com/pypa/twine) module: 

```
twine upload dist/*
```

NOTE: you can also test on the pypi test servers `testpypi.python.org/pypi`
before the real deployment. Note also that in case of a mistake, you can delete
an uploaded release on pypi, but you cannot re-upload another with the same
version number!

Also, the new release can be added to the Github by creating a new release from
the web interface.