Release

The release process consists of four steps: (1) release plan, (2) release preparation, (3) build and release, and (4) post release. Each of these steps is explained below.

Release Plan

  • Decide what features and bug fixes go into this release. Based on the features and bug fixes decided, update the documentation (in docs directory) accordingly.

  • Decide the release number (format: a.b.c where a is the major number, b is the minor number, and c is the micro number).

    • If the release includes only the bug fixes or minor feature enhancements, then increment the micro number (e.g., 0.1.3 from 0.1.2).

    • If the release includes new features, then increment the minor number (e.g., 0.2.0 from 0.1.0).

    • If there are major changes in the release, then increment the major number (e.g., 1.0.0 from 0.19.2).

  • Assign release owner(s) who will be responsible for this release (if there is only one person developing the project, then he/she will be the release owner). Specifically, the release owner(s) will manage the following tasks: (1) release preparation, (2) build and release, and (3) post release activities.

  • Create an 'issue' for this release in GitHub which describes the release plan and assign it to the owner(s) for this release.

Release Preparation: Preparing the package for release

  • Create an empty project web page for the current release (e.g. in the webserver where you host yourhome page and other project pages).

  • Create a release branch

    • If this is a major/minor release, create a new release branch from the master. Name the branch as rel_a.b.x (e.g., rel_1.2.x).

    • If this is a micro release, work on the same release branch where this bug fix is applied to (e.g., if you fix a bug in release 1.2.0, then work on the rel_1.2.x branch).

    • Checkout the release branch.

    • Add the required features/bug fixes decided for the current release in the branch. Remove other features/bug fixes that are not needed for this release from the branch.

    • Change the version number in 'setup.py' file (in the project root) and '__init__.py' file (in the main package) to the release number.

    • Ensure any new package dependencies have been added to 'setup.py's 'install_requires' list. Update the required versions of dependencies in 'setup.py'.

    • Update the versions of all entries in 'requirements.txt'.

    • Verify ~100% test coverage using the following command (from project root):

nosetests --with-coverage

The above command would require installing the coverage package (if not already installed) and it can installed using the following command:

pip install coverage

Note: If the package has Cython code then first execute the following command (from project root), and then execute nosetests:

python setup.py build_ext --inplace

    • Do a commit and push to check if Travis-CI passes all the test cases across different Python versions that the package is intending to support. (Travis-CI will use 'requirements.txt' to install dependencies)

    • Update the 'CHANGES.txt' file in the project root to contain the features/bug fixes added in the current release.

    • Commit and push all the changes.

    • Download the helper script to upload docs to your local directory. Now execute the script as shown below to build and push the latest docs:

Correct syntax: ./push_docs.sh [package_name] [branch_name] [html_dir_name] [tmp_dir_name]

Example usage: ./push_docs.sh py_stringmatching rel_0.2.x v0.2.x local_tmp

Build and Release

    • Checkout the release branch.

    • Build a source distribution using the following command (from project root):

python setup.py sdist --formats=gztar,zip

    • The above command will create the source distribution files in tar.gz and zip formats in 'dist' directory in project root.

    • Try installing them on different operating systems (e.g., Linux, OS X, Windows).

    • Log into PyPI webpage and, create a new version and upload the source distribution files.

  • Check if the package is displayed correctly at "https://pypi.python.org/pypi/py_stringmatching"

  • Go to the github repo and draft a new release. Here is a step-by-step guide to create a release.

  • Update the project web page with latest release information and important links.

Post Release

  • Announce the release in the other forums (e.g., DB world, Twitter).

  • Close the 'issue' created for this release in GitHub.