Maintainer's Release Workflow

Maintainer's Release Workflow

This page contains a step-by-step guide to releasing OpenCoarrays. In the future I hope to automate this further, based on watching for tags, however, for right now these steps are manual. In addition, I have created a page dedicated to the standard release notes template where a preview of the template can be seen, and the raw markdown can easily be copied to the clipboard.

Prerequisites

You should have a GPG key setup, with a public key pushed to the key servers and signed by other OpenCoarrays developers, and publicized in the appropriate locations, such as keybase.io. However, you can create a release without the GPG signature, and another OpenCoarrays maintainer can verify and sign the package after the fact since we always used detached signatures. Unfortunately setting up GPG is a pain, and there are a number of different good, but tin-foil-hat-y tutorials out there. I recommend just using https://gpgtools.org/ to setup and maintain your GPG public key.

In addition, you'll need to verify that the package builds locally, and passes all the tests after tagging it, and before releasing it. It's a good idea to do a sanity check using the release archive as well.

Warning!

Please DO NOT tag a release from the github web interface! This creates a dangling commit object that then gets tagged. The OpenCoarrays build system contains logic to embed the version number in builds when built from version control so that we may assist users in their debugging efforts. If you tag a release from the GitHub web interface, you will break this functionality.

This functionality uses git describe to return version numbers like 2.7.1-38-g90cfb59 which indicate the current version is 38 commits ahead of the last tag (2.7.1) on commit g90cfb59, allowing a precise mapping and checkout of the source code used to build that version of OpenCoarrays. If you create a tag based on a dangling commit object using the GitHub web interface, say version 2.8.0, then git describe will not give the "correct" answer, it will say, e.g., 2.7.1-41-0123abcd instead of 2.8.1-3-0123dcba.

Release procedure

1. Turn off branch protection on main for administrators in the settings.
2. git checkout main and get the latest version git pull origin main
3. Edit and commit the version number in .VERSION
4. Create a signed tag (if you have GPG setup, or an annotated tag if you don't):
   1. For a signed tag: git tag -s x.y.z <commit-sha>
   2. For an annotated tag: git tag -a x.y.z <commit-sha>
5. Checkout the tag: git checkout <x.y.z>
6. Build, test, install and uninstall OpenCoarrays to ensure that everything works as expected:

   cmake -B build -Wdev .
   cd build
   make -j 4 install
   ctest --output-on-failure
   make uninstall
   

7. Generate the source archive, the cryptographic checksums, and, if possible, the detached GPG signature of the cryptographic checksum using:

   make dist
   

8. Verify checksum, and signatures (if present):
   1. shasum -c opencoarrays-<x.y.z>-SHA256.txt on macOS or sha256sum -c opencoarrays-<x.y.z>-SHA256.txt on Linux
   2. gpg --verify opencoarrays-<x.y.z>-SHA256.txt.asc
   3. gpg --verify OpenCoarrays-<x.y.z>.tar.gz.asc
9. Extract and test the source archive outside of the git project, using sudo privileges if possible:

   mkdir ~/tmp
   cp OpenCoarrays-<x.y.z>.tar.gz ~/tmp
   cd ~/tmp
   tar -xvf OpenCoarrays-<x.y.z>.tar.gz
   cd OpenCoarrays-<x.y.z>
   cmake -B build -Wdev .
   cd build
   sudo make -j 4 install
   caf --version # double check things look ok
   caf --show
   cafrun --version
   cafrun --show
   sudo ctest --output-on-failure
   sudo make uninstall
   cd ~/tmp
   sudo rm -r OpenCoarrays-<x.y.z>
   

10. If everything is looking good, then push the tags and release!
    1. git push --tags origin
    2. Draft a new release or edit current draft (https://github.com/sourceryinstitute/OpenCoarrays/releases)
    3. Upload to the release assets area, NOT just in the text of the release:
       OpenCoarrays-<x.y.z>.tar.gz
opencoarrays-<x.y.z>-SHA256.txt
OpenCoarrays-<x.y.z>.tar.gz.asc (if gpg signed)
       opencoarrays-<x.y.z>-SHA256.txt.asc (if gpg signed)
11. Select <x.y.z> as the version to release and ensure that it says ✔️ Existing tag below it. You may need to refresh your browser or wait for the GitHub interface to realize you've pushed up your tag.
12. You should copy the release notes template as the starting point for the release message in github and edit the description of the release and the links that have comments saying they need to be updated.
13. Re-enable branch protection for main for administrators and prevent users from pushing to main in settings
14. Profit! (And checkout main locally so you're not on a detatched head: git checkout main)
15. Optional further steps: Submit a PR to update Homebrew:
    1. Copy the sha256 hash from opencoarrays-<x.y.z>-SHA256.txt to your clipboard
    2. Navigate to https://github.com/sourceryinstitute/OpenCoarrays/releases so you can get ready to copy the link to the release asset; it should look like:

       https://github.com/sourceryinstitute/OpenCoarrays/releases/download/<x.y.z>/OpenCoarrays-<x.y.z>.tar.gz
       

    3. Make sure HOMEBREW_DEVELOPER=1 and HOMBREW_FORCE_VENDOR_RUBY=1 are set and exported in your environment
    4. Run:

       brew bump-formula-pr --strict --url=https://github.com/sourceryinstitute/OpenCoarrays/releases/download/<x.y.z>/OpenCoarrays-<x.y.z>.tar.gz --sha256=<paste sha245 from clipboard> --verbose opencoarrays  
       

       If all goes well a page like https://github.com/Homebrew/homebrew-core/pull/45035 will open with your PR in the browser