Release Documentation

Introduction

This is the release documentation for releasing a new version of screed. This document is meant for screed release managers. Michael R. Crusoe and C. Titus Brown have released screed in the past. Jake Fenton is the first to release screed using this checklist.

Getting Started

  1. Start with a clean checkout:

    cd `mktemp -d`
    git clone [email protected]:dib-lab/screed.git
    cd screed
    
  2. Install/update versioneer:

    pip install versioneer
    versioneer install
    

    If there is a new version of versioneer, follow the instruction to update it and fix the configuration if needed:

    git diff
    versioneer install
    git commit -p -m "new version of versioneer.py"
    # or abandon the changes
    git checkout -- versioneer.py screed/_version.py screed/__init.py \
            MANIFEST.in
    
  3. Review the git logs since the previous release and that ChangeLog reflects the major changes:

    git log --minimal --patch \
            `git describe --tags --always --abbrev=0`..HEAD
    
  4. Review the issue list for any existing bugs that won’t be fixed in the release and ensure they’re documented in doc/known-issues.txt

  5. Verify that the build is clean: https://travis-ci.org/dib-lab/screed

  6. Set the new version number and release candidate:

    new_version=1.1
    rc=rc3
    

    Tag the release candidate with the new version prefixed by the letter ‘v’:

    git tag v${new_version}-${rc}
    git push --tags [email protected]:dib-lab/screed.git
    
  7. Test the release candidate:

    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} \
            https://github.com/dib-lab/screed.git
    cd screed
    make install-dependencies
    make install
    make test
    python -c 'import screed; print(screed.__version__)' # double-check version number
    
    
    # Test via pip
    cd ../../testenv2
    source bin/activate
    pip install -e \
            git+https://github.com/dib-lab/[email protected]${new_version}-${rc}#egg=screed
    cd src/screed
    make dist
    make install
    pip install pytest
    pytest --pyargs screed -m 'not known_failing'
    python -c 'import screed; print(screed.__version__)'
    cp dist/screed*tar.gz ../../../testenv3
    
    # test if the dist made in testenv2 is complete enough to build another
    # functional dist
    
    cd ../../../testenv3
    source bin/activate
    pip install pytest
    pip install screed*tar.gz
    pytest --pyargs screed -m 'not known_failing'
    python -c 'import screed; print(screed.__version__)'
    tar xzf screed*tar.gz
    cd screed*
    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: https://wiki.python.org/moin/TestPyPI. You may need to re-register:

    python setup.py register --repository test
    

    Now, upload the new release:

    python setup.py sdist upload -r test
    

    Test the PyPI release in a new virtualenv:

    cd ../../testenv4
    source bin/activate
    pip install -U setuptools pip
    pip install pytest
    pip install -i https://testpypi.python.org/pypi --pre --no-clean screed
    pytest --pyargs screed -m 'not known_failing'
    python -c 'import screed; print(screed.__version__)'
    cd build/screed
    ./setup.py test
    
  9. Do any final testing (acceptance tests, etc.) Note that the acceptance tests for screed are to run the khmer automated tests with the new version of screed installed and then to run the khmer acceptance tests.

  10. Make sure any release notes are merged into doc/release-notes/. Release notes should be written in the .md format to satisfy the requirements for GitHub release notes. The convert-release-notes make target can be used to generate .rst files from the .md notes.

How to make a final release

When you have 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 ../../../screed
    git tag v${new_version}
    python setup.py 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 [email protected]:dib-lab/screed.git
    git push --tags [email protected]:dib-lab/screed.git
    
  3. Add the release on GitHub, using the tag you just pushed. Name it “Version X.Y.Z” and copy/paste in the release notes.

  4. Update the Read the Docs to point to the new version. Visit https://readthedocs.org/builds/screed/ 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 https://readthedocs.org/dashboard/screed/versions/ under “Choose Active Versions”. Finally change the default version at https://readthedocs.org/dashboard/screed/advanced/ to the new version.

  5. Delete any RC tags created:

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

  7. Send email including the release notes to khmer@lists.idyll.org and khmer-announce@lists.idyll.org

Notes on this document

This is the procedure for cutting a new release of screed. It has been adapted from the release documentation for the khmer project, found at http://khmer.readthedocs.org/en/v1.1/release.html.