Releasing a new version

Once you are comfortable with the changes to be released, there is a few things you have to do to consider this software “released”.

It is worth mentioning that I will very probably script all (or almost all) of this, once I have the time / decide how to do it.

Pre-requisites

  • You need a github account with permissions for pushing new tags/releases
  • You need to be added to the PyPi project so you can submit new releases
  • Your ~/.pypirc is configured with your PyPi username and password
  • You need your GPG key signed by one of the other maintainers

Cutting the release

Usually involves a few steps (for simplicity, using version 0.0.1 to illustrate the examples)

  1. Updating the changelog: You create a new page in docs/changelog named docs/changelog/v0.0.1.rst
  2. Re-linking current changelog to new changelog: You re-point the symlink from docs/changelog/current.rst to docs/changelog/v0.0.1.rst
  3. Commit your changelog change
  4. Update the version: Need to bump the version in clustoapi/__init__.py to reflect the new 0.0.1 version
  5. Commit your version bump change
  6. Tag the release: You need to git tag -s v0.0.1 at this point. Pay attention to the -s switch, this implies the tag will be signed with your GPG key (optionally, use -u to specify which key to use if you don’t want to use the default)

Publishing the release

This entails publishing the release on github. Once you publish the release on github, a tweet will be posted shortly (< 1 hour after) to the @clustodotorg account.

  1. Push your changes up to the repo: You need to both git push and git push --tags for this operation, your changes should be visible now, and the new tag should appear in https://github.com/clusto/clusto-apiserver/tags
  2. Edit the tag so it turns into a release in github: Draft a new release https://github.com/clusto/clusto-apiserver/releases/new and pick the tag you recently created. The title of the release should be “Version 0.0.1” (to continue with the sample version) and the body should be the contents of the docs/changelog/v0.0.1.rst file. Keep in mind that the format is Markdown while the documentation is ReStructured Text, so adjust as necessary (mainly titles change i.e. replace ^ for -)

At this point the release should appear in the github releases page https://github.com/clusto/clusto-apiserver/releases/

Uploading to PyPi

Finally, publishing the module / source code to PyPi should be a single step:

  • Sign and upload the new version tarball: Basically run (from the project’s root dir):

    python setup.py sdist upload --sign [--identity <GPG identity>]

    What this does is:

    1. Creates a tarball under the dist/ directory (the sdist command)
    2. Using the --sign flag signs the tarball using your GPG key (depending on your setup, you may get prompted for your GPG password). Optionally, you can use the --identity argument if you aren’t using your default identity to sign
    3. Uploads the recently created and signed tarball to PyPi (the upload command)

At this point, the new version should be visible in https://pypi.python.org/pypi/clusto-apiserver