How to make a khmer release

Michael R. Crusoe is the current release maker. This is his checklist.

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

   cd `mktemp -d`
   git clone git@github.com:ged-lab/khmer.git
   cd khmer
   

2. (Optional) Check for updates to versioneer:

   pip install versioneer
   versioneer-installer
   
   git diff
   
   ./setup.py versioneer
   git diff
   git commit -m -a "new version of versioneer.py"
   # or
   git checkout -- versioneer.py khmer/_version.py khmer/__init__.py MANIFEST.in
   

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: http://ci.ged.msu.edu/job/khmer-multi/

6. Tag the branch with the release candidate version number prefixed by the letter ‘v’:

   new_version=1.0.1
   git tag v${new_version}-rc1
   git push --tags git@github.com:ged-lab/khmer.git
   

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}-rc1 https://github.com/ged-lab/khmer.git
   cd khmer
   make install
   make test
   normalize-by-median.py --version # double-check version number
   
   # Secondly we test via pip
   
   cd ../../testenv2
   source bin/activate
   pip install -e git+https://github.com/ged-lab/khmer.git@v${new_version}-rc1#egg=khmer
   cd src/khmer
   make dist
   make install
   make test
   normalize-by-median.py --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 khmer*tar.gz
   tar xzf khmer*tar.gz
   cd khmer*
   make dist
   make test
   

8. Publish the new release on the testing PyPI server:

   python setup.py register --repository test
   

   Change your PyPI credentials as documented in https://wiki.python.org/moin/TestPyPI:

   python setup.py sdist upload -r test
   

   Test the PyPI release in a new virtualenv:

   cd ../../testenv4
   source bin/activate
   pip install screed
   pip install -i https://testpypi.python.org/pypi --pre --no-clean khmer
   normalize-by-median.py --version 2>&1 | awk ' { print $2 } '
   cd build/khmer
   make test
   

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

   cd ../../../khmer
   git tag v${new_version}
   python setup.py register sdist upload
   

10. Delete the release candidate tag and push the tag updates to github.:

    git tag -d v${new_version}-rc1
    git push git@github.com:ged-lab/khmer.git
    git push --tags git@github.com:ged-lab/khmer.git
    

11. Make a binary wheel on OS X.:

    virtualenv build
    cd build
    source bin/activate
    pip install khmer==${new_version}
    pip install wheel
    cd build/khmer
    ./setup.py bdist_wheel upload
    

12. Tweet about the new release. Optionally send email including the contents of the ChangeLog to khmer@lists.idyll.org and khmer-announce@lists.idyll.org

Upstream sources

ez_setup.py is from https://bitbucket.org/pypa/setuptools/raw/bootstrap/

versioneer.py is from https://raw.github.com/warner/python-versioneer/master/versioneer.py

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

Explanation

Versioneer, from https://github.com/warner/python-versioneer, is used to determine the version number and is called by Setuptools and Sphinx. See the files versioneer.py, the top of khmer/__init__.py, khmer/_version.py, setup.py, and doc/conf.py for the implementation.

The version number is determined through several methods: see https://github.com/warner/python-versioneer#version-identifiers

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/_version.py via the $Format:%d$ and $Format:%H$ placeholders enabled by the “export-subst” entry in .gitattributes.

Non source distributions will have a customized khmer/_version.py that contains hard-coded version strings. (see build/*/khmer/_version.py after a python setup.py build for an example)

ez_setup.py bootstraps Setuptools (if needed) by downloading and installing an appropriate version

comments powered by Disqus