dune-release.md

Using dune-release to release OCaml packages

Originally written 2020-05-16

dune-release is a good improvement over the old opam-publish, but releasing software is still clearly not a solved problem, and I find it hard to remember the exact steps involved in releasing an opam package, especially if some time has passed since the last release. This note is an attempt at having a place that I can refer to when occasionally releasing my software to opam.

1. First things first: lint your opam files:

$ dune-release lint

2. (Optional) Build a distribution archive to check that the project builds (optionally pass -p pkg1,pkg2) to build just a few packages. I've also found --skip-tests useful here for repos that have e.g. submodules.

$ dune-release distrib

3. Tag a VCS release in your repository:

$ dune-release tag x.y.z

4. Distribute the release archive and upload it to GitHub (don't forget to point dune-release at your changelog -- I've found the algorithm for finding the changes file is a little clunky):

$ dune-release distrib && dune-release publish distrib --change-log=./CHANGES.md

5. Package the opam release:

$ dune-release opam pkg -p pkg1,pkg2 --change-log=./CHANGES.md

6. Submit the release to the opam repository:

$ dune-release opam submit --change-log=./CHANGES.md

Thanks for this guide!

Just a small note: step 5 requires the DUNE_RELEASE_GITHUB_TOKEN env var to be available in the current session, to make it available:

export DUNE_RELEASE_GITHUB_TOKEN="ghp_<your_GitHub_token>"

Found the same issue but didn't had the env var, but the token was stored: ~/.config/dune/github.token change it and run again

the only permission needed for the token is just repo -> public_repo