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 git 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: git tag -s x.y.z <commit-sha> for a signed tag and git tag -a x.y.z <commit-sha> for an annotated tag
5. 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

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

make dist