Toil Release Instructions

1. Update the AWS instance typed by running:

   src/toil/utils/toilUpdateEC2Instances.py
   

   Commit the result and PR it. Wait for CI to run and for a reviewer to approve and merge it. This will take about a day.

2. Create branch releases/1.2.x:

    git checkout -b releases/1.2.x
   

3. In a direct commit/push to master, bump project version from 1.2.0a1 to 1.3.0a1 in version_template.py.

4. In a direct commit to releases/1.2.x, bump project version from 1.2.0a1 to 1.2.0 in version_template.py, and push.

    git add version_template.py
    git commit
    git push origin releases/1.2.x
   

5. Build the updated branch with a clean build, to make sure src/toil/version.py is correct.

    git checkout releases/1.2.x
    virtualenv --system-site-packages -p python3.9 --never-download venv
    # Or: python3.9 -m venv venv
    . venv/bin/activate
    make clean
    make prepare
    make develop extras='[all]'  # (must be the same as the extras in Dockerfile.py)
   

   TODO: Should there be a test step here???

6. Once the tests in step 2 finish, tag the HEAD commit on the releases/1.2.x branch as releases/1.2.0 and push that tag:

   git tag -a 'releases/1.2.0' -m 'release 1.2.0'
   git push origin releases/1.2.0
   

7. On GitHub create a release pointing to this tag. Include release notes giving an overview of bug fixes and new features in this release. Use the Draft Changelog, or the diff linked from the number of commits to master since the last release, to see the changes. Note contributors.

8. CI/CD will create and upload the appliance images to quay.io. This used to be done manually with make push_docker.

9. Once the images are created (CI/CD appliance tests conclude), tag the images with latest and 1.2.0: https://quay.io/repository/ucsc_cgl/toil?tab=tags. Assign the tags to the build for the latest Python release. Since the image is multi-architecture, this can't be done with docker tag; you need to use a tool like regctl:

regctl image copy quay.io/ucsc_cgl/toil:8.1.0b1-4bb05349c027096ab4785259e39b2648118b5dd7-py3.13 quay.io/ucsc_cgl/toil:8.1.0b1
regctl image copy quay.io/ucsc_cgl/toil:8.1.0b1-4bb05349c027096ab4785259e39b2648118b5dd7-py3.13 quay.io/ucsc_cgl/toil:latest

1. Build the packages for PyPI.

    rm -rf dist
    pip install --upgrade pip
    pip install --upgrade setuptools wheel build
    python -m build
   

2. Double-check to make sure you aren't including files to the release that shouldn't go there, like one-off development files left lying around. If in doubt, use a fresh clone to do the build (for version.py) and package build!

3. PyPI - WARNING: This step cannot be redone! First make sure that the proper credentials are in ~/.pypirc, then:

    pip install --upgrade twine
    twine upload dist/*
   

4. In a direct edit to the releases/1.2.x branch on GitHub, bump project version from 1.2.0 to 1.2.1a1 in version_template.py.

5. On http://readthedocs.org/projects/toil/, check to make sure that the latest docs built correctly.

Hotfix Release, e.g. 1.2.1

1. Create a fresh clone and switch to the branch releases/1.2.x:

    git clone https://github.com/Databiosphere/toil.git
    git checkout releases/1.2.x
   

2. Do step #3 above and the following steps, using 1.2.1, instead of 1.2.0.