Releasing a new version of sourmash

These are adapted from the khmer release docs, originally written by Michael Crusoe.

Remember to update release numbers/RC in:

  • this document

Testing a release

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

cd $(mktemp -d)
git clone
cd sourmash

2. Set your new version number and release candidate (you might want to check for next version number):


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

git tag -a v${new_version}${rc}
git push --tags

3. Test the release candidate. Bonus: repeat on Mac OS X:

cd ..
python -m venv testenv1
python -m venv testenv2
python -m venv testenv3
python -m venv testenv4

# First we test the tag

cd testenv1
source bin/activate
git clone --depth 1 --branch v${new_version}${rc}
cd sourmash
pip install -r requirements.txt
make test

# Secondly we test via pip

cd ../../testenv2
source bin/activate
pip install -U setuptools
pip install -e git+${new_version}${rc}#egg=sourmash[test]
cd src/sourmash
make test
make dist
cp dist/sourmash*tar.gz ../../../testenv3/

# Is the distribution in testenv2 complete enough to build another
# functional distribution?

cd ../../../testenv3/
source bin/activate
pip install -U setuptools
pip install sourmash*tar.gz
pip install pytest
tar xzf sourmash-${new_version}${rc}.tar.gz
cd sourmash-${new_version}${rc}
pip install -r requirements.txt
make dist
make test  ## Currently failing, we don't have all the test data...

4. Publish the new release on the testing PyPI server. You will need to change your PyPI credentials as documented here: We will be using twine to upload the package to TestPyPI and verify everything works before sending it to PyPI:

pip install twine
twine upload --repository-url dist/sourmash-${new_version}${rc}.tar.gz

Test the PyPI release in a new virtualenv:

cd ../../testenv4
source bin/activate
pip install -U setuptools
# install as much as possible from non-test server!
pip install screed pytest numpy matplotlib scipy khmer "ijson<2.5"
pip install -i --pre sourmash
sourmash info  # should print "sourmash version ${new_version}${rc}"

5. Do any final testing:

  • check that the binder demo notebook is up to date
  • check wheels from github releases

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. Write the changes from previous version in the tag commit message. git log --oneline can be useful here, because it can be used to compare the two versions (and hopefully we used descriptive PR names and commit messages). An example comparing 2.2.0 to 2.1.0: git log --oneline v2.1.0..v2.2.0
cd ../sourmash
git tag -a v${new_version}
  1. Publish the new release on PyPI (requires an authorized account).
make dist
twine upload dist/sourmash-${new_version}.tar.gz
  1. Delete the release candidate tag and push the tag updates to GitHub:
git tag -d v${new_version}${rc}
git push --tags
git push --delete v${new_version}${rc}
  1. 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:
  2. Upload wheels from GitHub Releases to PyPI. hub makes this easier, but you can also manually download all the files from
mkdir -p wheel && cd wheel
hub release download v${new_version}
twine upload *.whl


The BiocondaBot has an autobump feature that should pick up new releases from PyPI, and open a PR in Bioconda. Review any changes (especially dependency versions, since these don’t get picked up).

This is an example PR (for 2.1.0):

Announce it!

If a bioinformatics software is released and no one tweets, is it really released?

Examples: 2.0.0 2.0.1 2.1.0

To test on a blank Ubuntu system

apt-cache update && apt-get -y install python-dev libfreetype6-dev && \
pip install sourmash[test]