.. vim: set filetype=rst

===========================
How to make a khmer release
===========================

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

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

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

#. (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

#. 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

#. Review the issue list for any new bugs that will not be fixed in this
   release. Add them to ``doc/known-issues.txt``

#. Verify that the build is clean: http://ci.ged.msu.edu/job/khmer-multi/

#. 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

#. 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

#. 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

#. 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

#. 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

#. 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

#. 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