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.

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 master for administrators in the settings.
2. git checkout master and get the latest version git pull origin master
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:

mkdir build
cd build
cmake -Wdev ..
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>
mkdir build
cd build
cmake -Wdev ..
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:
       1. OpenCoarrays-<x.y.z>.tar.gz
       2. opencoarrays-<x.y.z>-SHA256.txt
       3. OpenCoarrays-<x.y.z>.tar.gz.asc (if gpg signed)
       4. 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 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 master for administrators and prevent users from pushing to master in settings
14. Profit! (And checkout master locally so you're not on a detatched head: git checkout master)