Releasing a new version of khmer

How to make a khmer release candidate

Michael R. Crusoe, Luiz Irber, and C. Titus Brown have all been release makers, following this checklist by MRC.

  1. The below should be done in a clean checkout:

    cd `mktemp -d`
    git clone
    cd khmer
  2. (Optional) Check for updates to versioneer:

    pip install versioneer
    git diff
    ./ versioneer
    git diff
    git commit -m -a "new version of"
    # or
    git checkout -- khmer/ khmer/
  3. Review the git logs since the last release and diffs (if needed) and ensure that the Changelog is up to date:

    git log --minimal --patch `git describe --tags --always --abbrev=0`..HEAD
  4. Review the issue list for any new bugs that will not be fixed in this release. Add them to doc/known-issues.txt

  5. Verify that the build is clean:

  6. Set your new version number and release candidate:


    and then tag the release candidate with the new version number prefixed by the letter ‘v’:

    git tag v${new_version}-${rc}
    git push --tags
  7. Test the release candidate. Bonus: repeat on Mac OS X:

    cd ..
    virtualenv testenv1
    virtualenv testenv2
    virtualenv testenv3
    virtualenv testenv4
    # First we test the tag
    cd testenv1
    source bin/activate
    git clone --depth 1 --branch v${new_version}-${rc}
    cd khmer
    make install
    make test --version # double-check version number
    # Secondly we test via pip
    cd ../../testenv2
    source bin/activate
    pip install -U setuptools==3.4.1
    pip install -e git+${new_version}-${rc}#egg=khmer
    cd src/khmer
    make dist
    make install
    make test --version # double-check version number
    cp dist/khmer*tar.gz ../../../testenv3/
    # Is the distribution in testenv2 complete enough to build another
    # functional distribution?
    cd ../../../testenv3/
    source bin/activate
    pip install -U setuptools==3.4.1
    pip install khmer*tar.gz
    tar xzf khmer*tar.gz
    cd khmer*
    make dist
    make test
  8. Publish the new release on the testing PyPI server. You will need to change your PyPI credentials as documented here: You may need to reregister:

    python register --repository test

    Now, upload the new release:

    python sdist upload -r test

    Test the PyPI release in a new virtualenv:

    cd ../../testenv4
    source bin/activate
    pip install -U setuptools==3.4.1
    pip install screed nose
    pip install -i --pre --no-clean khmer --version 2>&1 | awk ' { print $2 } '
    cd build/khmer
    ./ nosetests
  9. Do any final testing (BaTLab and/or acceptance tests).

  10. Make sure any release notes are merged into doc/release-notes/.

How to make a final release

When you’ve got a thoroughly tested release candidate, cut a release like so:

  1. Create the final tag and publish the new release on PyPI (requires an authorized account).:

    cd ../../../khmer
    git tag v${new_version}
    python register sdist upload
  2. Delete the release candidate tag and push the tag updates to github.:

    git tag -d v${new_version}-${rc}
    git push
    git push --tags
  3. Add the release on github, using the tag you just pushed. Name it ‘version X.Y.Z’, and copy and paste in the release notes.

  4. Make a binary wheel on OS X.:

    virtualenv build
    cd build
    source bin/activate
    pip install -U setuptools==3.4.1 wheel
    pip install --no-clean khmer==${new_version}
    cd build/khmer
    ./ bdist_wheel upload
  5. Update Read the Docs to point to the new version. Visit and ‘Build Version: master’ to pick up the new tag. Once that build has finished check the “Activate” box next to the new version at under “Choose Active Versions”. Finally change the default version at to the new version.

  6. Delete any RC tags created:

    git tag -d ${new_version}-${rc}
    git push origin :refs/tags/${new_version}-${rc}
  7. Tweet about the new release.

  8. Send email including the release notes to and

BaTLab testing

The UW-Madison Build and Test Lab provides the khmer project with a free cross-platform testing environment.

  1. Connect to their head node:

  2. Move into the khmer directory and download a release from PyPI’s main server or the test PyPI server:

    cd khmer/
    vim khmer-v1.0.inputs # change the 'scp_file' to point to the release
    vim # change 'project_version' at bottom

Setuptools Bootstrap is from

Before major releases it should be examined to see if there are new versions available and if the change would be useful

Versioning Explanation

Versioneer, from, is used to determine the version number and is called by Setuptools and Sphinx. See the files, the top of khmer/, khmer/,, and doc/ for the implementation.

The version number is determined through several methods: see

If the source tree is from a git checkout then the version number is derived by git describe --tags --dirty --always. This will be in the format ${tagVersion}-${commits_ahead}-${revision_id}-${isDirty}. Example: v0.6.1-18-g8a9e430-dirty

If from an unpacked tarball then the name of the directory is queried.

Lacking either of the two git-archive will record the version number at the top of khmer/ via the $Format:%d$ and $Format:%H$ placeholders enabled by the “export-subst” entry in .gitattributes.

Non source distributions will have a customized khmer/ that contains hard-coded version strings. (see build/*/khmer/ after a python build for an example) bootstraps Setuptools (if needed) by downloading and installing an appropriate version

comments powered by Disqus

Table Of Contents

Previous topic

Known Issues

Next topic

Crazy ideas

This Page