Releases

Cactus release process

The latest stable release of cactus is found at:

• https://github.com/ComparativeGenomicsToolkit/cactus/releases

Docker images are available from:

• https://quay.io/repository/comparative-genomics-toolkit/cactus?tab=tags

Versioning

Cactus currently does not implement semantic versioning. We do try to minimize breaking changes but there are no guarantees in place.

We do try to maintain a semantic-like naming scheme for releases (e.g. the major release after 1.7.0 is 1.8.0).

Before a release

1. Update getDockerRelease() function in src/cactus/shared/common.py to return the new release
2. Update version field in setup.py to reflect the new version
3. Update the version in the virtualenv name in BIN_INSTALL.md
4. Update all instances of the version name in doc/progressive.md
5. Maintain ReleaseNotes.md in the tree as changes are made, in newest-first order
   • Record any new features and important changes, include those in submodules.
   • Make note of any breaking changes, include those in submodules.
   • It may help to consult the log of commits since the last release.
6. Check that all unit and integration tests (both Travis and GitLab) have been run.

Release process

To cut a new release:

1. Ensure the section for this release in ReleaseNotes.md is current. It may help to consult the log of commits or pull requests since the last release.
2. Edit ReleaseNotes.md and add release number and date.
3. Create a new release on Github
   1. Look up the next release number
   2. Tag it vX.Y.Z
   3. Title it Cactus X.Y.Z 2020-00-00
   4. Fill in release description:
      1. Copy release description template below, edit to set release number.
      2. Inserted the section from ReleaseNotes.md describing this release.
   5. Mark it as a pre-release
   6. Publish it (which tags the commit and hopefully kicks off the Docker build on Quay)
4. Produce a buildable source tarball, containing code for cactus and all submodules, and upload it to the release.

   make srcRelease
   

5. Build and upload a static Linux binary package on a CentOS 7.5 system. This has the /bin/ files and python source needed to pip install cactus for the release. On Ubuntu, make sure to use an installed-from-source hdf5 (configured with --enable-static --disable-shared)

   make binRelease
   

6. Verify that the Docker image is at quay.io with the SHA returned by git rev-parse vX.Y.Z.
7. Tag Docker image (this script has never worked, you must tag it manually on quay):

   ./build-tools/quayTagRelease
   

   or tag on the quay.io page
8. Make a CPU Docker image. This script will prompt you to push the image, type y to accept. It requires having write access to quay and having logged in with something like docker login --username $QUAY_USERNAME --password $QUAY_PASSWORD quay.io

   ./build-tools/makeCpuDockerRelease
   

9. Make a GPU Docker image. If desired, update the Segalign commit in build-tools/Segalign.commit to use a newer version. As above, you must type y at the end to push it.

   ./build-tools/makeGpuDockerRelease
   

   1. It's advisable to run a gpu test on Terra if possible, especially if updating Segalign. This can be done with

   cactus-prepare examples/evolverMammals.txt --wdl --noLocalInputs --alignCores 2 --defaultMem 16 --gpu --gpuCount 8 > evolver.gpu.wdl
   

   Then making a workflow and uploading config-prepared.xml and examples/evolverMammals.txt as inputs.
10. Verify that all links are working
11. Edit the release and mark it as no longer a pre-release, to make it the latest stable release.
12. Send an announcement to cactus-announce@googlegroups.com, pointing to release notes at https://github.com/ComparativeGenomicsToolkit/cactus/releases/vX.Y.X/.
13. Also post the announcement in the GitHub Discussions Announcements category.

Release notes template

Cactus X.Y.Z is available in the following forms:
- Docker Image: `quay.io/comparative-genomics-toolkit/cactus:vX.Y.Z`
  GPU-accelerated Docker Image: `quay.io/comparative-genomics-toolkit/cactus:vX.Y.Z-gpu`
  Install instructions in [README.md](https://github.com/ComparativeGenomicsToolkit/cactus/blob/vX.Y.Z/README.md)
- Pre-compiled Binaries Linux Tarball: [cactus-bin-vX.Y.Z.tar.gz](https://github.com/ComparativeGenomicsToolkit/cactus/releases/download/vX.Y.Z/cactus-bin-vX.Y.Z.tar.gz)
- Pre-compiled Binaries For Older CPU Architectures (no pangenome support) Linux Tarball: [cactus-bin-legacy-vX.Y.Z.tar.gz](https://github.com/ComparativeGenomicsToolkit/cactus/releases/download/vX.Y.Z/cactus-bin-legacy-vX.Y.Z.tar.gz)
  Install instructions in [BIN-INSTALL.md](https://github.com/ComparativeGenomicsToolkit/cactus/blob/vX.Y.Z/BIN-INSTALL.md)
- Source Tarball: [cactus-vX.Y.Z.tar.gz](https://github.com/ComparativeGenomicsToolkit/cactus/releases/download/vX.Y.Z/cactus-vX.Y.Z.tar.gz)
  Install instructions in [README.md](https://github.com/ComparativeGenomicsToolkit/cactus/blob/vX.Y.Z/README.md)

**WARNING**: do not use the github automatically generated source files (`Source code (zip)` or `Source code (tar.gz)`), these are not correct.

The Docker images and binaries linked above are built for the [Intel Nehalem architecture](https://en.wikipedia.org/wiki/Nehalem_(microarchitecture)) and require a CPU that supports it (typically something from 2008 or later), except the "Pre-compiled Binaries For Older CPU Architectures" which should be compatible with any 64-bit architecture (but don't yet support the Cactus's pangenome pipeline). 
  
Please subscribe to the [cactus-announce](https://groups.google.com/d/forum/cactus-announce) low-volume mailing list to receive notice of Cactus release.

## Release notes
 <copy ReleaseNotes.md for this release here>

References

• Information on tag finding with Git
• This process shamelessly copied from vg