RELEASE.md

Release process

This file documents the necessary steps for releasing Irmin to its various users (via GitHub, opam-repository and Tezos).

At a high level, releasing Irmin consists of publishing the following artefacts:

• a Git commit tag;
• a set of documentation on GitHub pages (e.g. mirage.github.io/irmin);
• a release archive (.tbz file containing the project source) on GitHub;
• a set of .opam files in opam-repository that point to this release archive;
• (optionally) a copy of these .opam files in the Tezos opam-repository.

Most of this can be handled automatically by dune-release, as described in the instructions below.

Releasing to opam-repository and GitHub

• Check that no .opam files contain pin-depends fields. If so, release those packages first.

; git grep -A 10 "pin-depends" *.opam

• Make a pull-request to this repository containing pre-release changes (drop pin-depends, add release number to CHANGES.md, any new constraints) and an empty commit to host the release tag.

; git fetch upstream
; git checkout -B release-X.Y.Z upstream/main
; git commit -m "Prepare X.Y.Z release" -- CHANGES.md
; git commit --allow-empty -m "Release X.Y.Z"
; hub pull-request

• Wait for the CI to pass on the release PR, then perform the following steps to release to opam-repository:

; opam pin add odoc.2.0.0 https://github.com/ocaml/odoc.git  # Use a modern Odoc

; dune-release tag                        #  Create appropriate Git tag by reading CHANGES.md
; dune-release distrib --skip-tests       #  Build release archive
; dune-release publish distrib --verbose  #  Push release archive to GitHub
; dune-release publish doc --verbose      #  Push documentation to GitHub pages
; dune-release opam pkg                   #  Generate `opam` files for `opam-repository`
; dune-release opam submit                #  Make PR to `opam-repository`

• Once the release PR is merged on opam-repository, merge the release PR on the development repository. If any changes to .opam files were necessary in the opam-repository PR, add those to the release PR before merging.

Re-cutting a failed Opam release

It may be necessary to re-cut an attempted release, for instance if the opam-repository CI raised issues that couldn't be fixed via if the opam-repository.

First delete the release distribution via the GitHub UI, then cleanup the Git tags and re-perform the required release steps:

; git tag -d X.Y.Z                     #  Erase git tag locally
; git push -d upstream X.Y.Z           #  Erase git tag on GitHib
; dune-release distrib --skip-tests
; dune-release publish doc --verbose   # ... if necessary
; dune-release opam pkg
; dune-release opam submit ^C          #  Exit at prompt to avoid creating pull request
; cd <opam-repository>
; git push -u origin --force           #  Add new `.opam` files to PR

Releasing to Tezos' opam-repository

The Tezos project uses its own opam-repository to source its dependencies, so upgrading its dependencies requires making a separate release to this after having released to the main opam-repository. The process is as follows:

for p in <released_packages>; do
  # Remove old version of this package from Tezos' opam-repository
  rm ~/t/tezos-opam-repository/packages/$p/*/ -rf

  # Copy opam file for the new release of this package
  cp ~/t/{opam-repository,tezos-opam-repository}/packages/$p/$p.<release_version> -r
done

(The above process is somewhat automated by this script.) Once this is done, make an MR to the Tezos opam-repository and – if necessary – a corresponding MR to Tezos to adjust to any API changes.