Edit on GitHub

Releasing

Releasing a new version

To release a new version, run the provided bash script from the master branch of the repository:

bash tools/release.sh $RELEASE_VERSION

where $RELEASE_VERSION is a valid semantic version, without a v prefix (i.e. 1.2.3 is correct, v1.2.3 is not).

The script will:

  • check that the user is on the master branch.
  • check that there are no uncommitted changes.
  • check that the desired version is not already present in the repo.
  • check that the version argument matches the expected "X.Y.Z".
  • check that the version matches the version reported in Project.toml
  • check that CHANGELOG.md has an entry for the release version, and use it to generate release notes.

If these conditions are met, then the script will create a release draft. This draft can be inspected on github (see releases) and approved.

The script requires a working installation of python3 and gh (instructions for installation on linux).

CI for new releases

Continuous integration (CI) will build a new version of the Docker container (see Dockerfile) on every pushed git tag (or every commit on an open pull request).

The CI workflow will build the container image and will push it to Docker Hub. The image will be tagged with:

  • latest (and will overwrite existing latest tag there)
  • $RELEASE_VERSION

Both tags should point to the same image, i.e. their sha hashes should be exactly the same.

This image version can then be referred to as:

  • neherlab/pangraph:$RELEASE_VERSION
  • neherlab/pangraph:latest
  • neherlab/pangraph (which is the same as neherlab/pangraph:latest)

for example in docker pull and docker run commands.

Monitoring and debugging CI build

The status of the builds can be seen on GitHub Actions page:

https://github.com/neherlab/pangraph/actions

Verifying CI build

After CI build successfully finishes, check Docker Hub to ensure that the new tag is present and that the "latest" tag is updated and points to the same hash:

https://hub.docker.com/r/neherlab/pangraph

Pull and run the new version to make sure it works as expected:

docker pull neherlab/pangraph:$RELEASE_VERSION

docker run --rm -it \
  --name "pangraph-$(date +%s)" \
  --volume="$(pwd)/path-to-fasta:/workdir" \
  --user="$(id -u):$(id -g)" \
  --workdir=/workdir neherlab/pangraph:$RELEASE_VERSION \
  bash -c "pangraph build --circular --alpha 0 --beta 0 /workdir/test.fa"

Here we mount local directory path-to-fasta as /workdir so that pangraph can read the /workdir/test.fa" file.

👷 TODO: implement automated tests

Modifying continuous integration workflow

See .github/workflows/build.yml

Modifying Docker image

See Dockerfile