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 a fresh clone and create branch releases/1.2.x:

    git clone git@github.com:DataBiosphere/toil.git
    cd toil
    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 in your clone, 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. In your fresh clone from step 1 (or a new one), build the updated branch. Don't use a development repository where a src/toil/version.py already exists!

    git clone https://github.com/Databiosphere/toil.git
    cd toil
    git checkout releases/1.2.x
    virtualenv --system-site-packages -p python3.9 --never-download venv
    . venv/bin/activate
    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.

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

     rm -rf dist
     pip install pip --upgrade
     pip install setuptools wheel build twine --upgrade
     python -m build -n
     twine upload dist/*
    

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

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