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.

Most of the management commands have been directly placed inside the
Makefile: `python setup.py make [alias]`, (or simply `make [alias]` in
UNIX-like environments).

Note: to use the Makefile on Windows, you need to install make.exe,
for example by installing [MinGW MSYS](http://www.mingw.org/wiki/msys).


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

The tqdm repository managers should regularly bump the version number in the
[_version.py](https://raw.githubusercontent.com/tqdm/tqdm/master/tqdm/_version.py)
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.


CHECKING SETUP.PY
-----------------

To check that the `setup.py` file is compliant with PyPi requirements (e.g.
version number; reStructuredText in README.rst) use the following command:

```
python setup.py check --restructuredtext --strict
```

If you happen to mistakenly upload a broken release to PyPi,
you can fix the metadata by using: `python setup.py make pypimeta`
or `python setup.py register`.


MERGING PULL REQUESTS TO MASTER
----------------------------------------

This section describes how to cleanly merge PRs:

#### Step 1: From your project repository, bring in the changes and test (replace pr-branch-name by your Pull Request branch name):
```
git fetch origin
git checkout -b pr-branch-name origin/pr-branch-name
git rebase master
```

If there are conflicts:
```
git mergetool
git rebase --continue
```

#### Step 2: Update branch with the rebased history:
```
git push origin pr-branch-name --force
```

Note: NEVER just `git push --force`, this will push all your branches and overwrite the remote repo! Always precise what branch you target.
Note 2: if you are not a maintainer, you can stop here.

#### Step 3: Merge the changes in Master:
```sh
git checkout master
git merge --no-ff pr-branch-name
```

#### Step 4: Check tests:
```sh
python setup.py make testnose
python setup.py make testsetup
```

#### Step 5: Bump version in tqdm/_version.py (by using your text editor) and modify last commit:
```sh
git add tqdm/_version.py
git commit --amend
Add "+ bump version" in the commit message
```

#### Step 6: Push onto master:
```sh
git push origin master
```


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 make installdev
```

Secondly, ensure you bump the version, commit **and** tag. The tag format is
typically `v{major}.{minor}.{patch}`, for example: `v4.4.1`.
The current commit's tag is used in the version checking and generation process.
If the current commit is not tagged appropriately, the version will
display as `v{major}.{minor}.{patch}-{commit_hash}`.

Finally, build tqdm into a distributable python package:

```
python setup.py make build
```

This will generate several builds in the `dist/` folder. On non-windows
machines the windows ``exe`` installer may fail to build. This is normal.

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

```
python setup.py make pypi
```

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!
- in case of a mistake in the metadata on pypi (like the long description README
getting garbled because of a silent error), you can use the following
command to update the metadata: `make pypimeta` or `python setup.py register`

Also, the new release can (should) be added to `github` by creating a new
release from the web interface, uploading packages from the `dist/` folder
created by `python setup.py make build`.


SUMMARY
-------

1. bump version in `tqdm/_version.py`
2. test (e.g. `python setup.py make alltests`)
3. `git commit`
4. `git push`
5. wait for tests to pass
    a) in case of failure, fix and go back to (2)
6. `git tag vM.m.p`
7. `python setup.py make distclean`
8. `python setup.py make build`
9. `python setup.py make pypi`
