Making a release¶

This document guides a contributor through creating a release of the wordcloud python packages.

A core developer should follow these steps to trigger the creation and upload of a release X.Y.Z of wordcloud on PyPI..

Documentation conventions¶

The commands reported below should be evaluated in the same terminal session.

Commands to evaluate starts with a dollar sign. For example:

$ echo "Hello"
Hello

means that echo "Hello" should be copied and evaluated in the terminal.

Setting up environment¶

First, register for an account on PyPI.
If not already the case, ask to be added as a Package Index Maintainer.

Create a ~/.pypirc file with your login credentials:

[distutils]
index-servers =
  pypi
  pypitest

[pypi]
username=<your-username>
password=<your-password>

[pypitest]
repository=https://test.pypi.org/legacy/
username=<your-username>
password=<your-password>

where <your-username> and <your-password> correspond to your PyPI account.

PyPI: Step-by-step¶

Make sure that all CI tests are passing: AppVeyor, CircleCI and Travis CI.
List all tags sorted by version

$ git tag -l | sort -V

Choose the next release version number

release=X.Y.Z
Warning

To ensure the packages are uploaded on PyPI, tags must match this regular expression: ^[0-9]+(\.[0-9]+)*(\.post[0-9]+)?$.

Download latest sources

cd /tmp && git clone git@github.com:amueller/word_cloud && cd word_cloud

In doc/changelog.rst change Next Release section header with WordCloud X.Y.Z and commit the changes using the same title

$ git add doc/changelog.rst
$ git commit -m "WordCloud ${release}"

Tag the release

$ git tag --sign -m "WordCloud ${release}" ${release} master
Note

We recommend using a GPG key to sign the tag.

Publish the tag

$ git push origin ${release}
Note

This will trigger builds on each CI services and automatically upload the wheels and source distribution on PyPI.

Check the status of the builds on AppVeyor, CircleCI and Travis CI.
Once the builds are completed, check that the distributions are available on PyPI.
Create a clean testing environment to test the installation

$ mkvirtualenv wordcloud-${release}-install-test && \
  pip install wordcloud && \
  python -c "import wordcloud;print(wordcloud.__version__)"
Note

If the mkvirtualenv is not available, this means you do not have virtualenvwrapper installed, in that case, you could either install it or directly use virtualenv or venv.

Cleanup

$ deactivate  && \
  rm -rf dist/* && \
  rmvirtualenv wordcloud-${release}-install-test

Add a Next Release section back in doc/changelog.rst, merge the result and push local changes:
```
$ git push origin master
```