tqdm/RELEASE

HOW TO MANAGE A NEW RELEASE
=============================

This file is intended for the project's maintainers and it describes
how to update, build and upload a new release.


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-semanticversion/)
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, check `setup.py` and `MANIFEST.in`, which define the packaging
process and info that will be uploaded to [pypi](pypi.python.org).

Check the result by using the following commands:

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

Secondly, 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
- 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.