From b6efddf8fdd9b702e63bd400a1133d35f0398965 Mon Sep 17 00:00:00 2001 From: Christine Rose Date: Wed, 18 Sep 2024 23:26:25 -0700 Subject: [PATCH] Edits & formatting --- RELEASE.md | 50 +++++++++++++++++++++++++------------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index 185e893c15..8900bb386a 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -1,17 +1,17 @@ -# Release process +# Release Process This file documents the necessary steps for releasing Irmin to its various users -(via GitHub, `opam-repository` and Tezos). +(via GitHub, `opam-repository`, and Tezos). At a high level, releasing Irmin consists of publishing the following artefacts: -- a Git [commit tag][git-tags]; -- a set of documentation on GitHub pages (e.g. [`mirage.github.io/irmin`][pages-docs]); -- a release archive (`.tbz` file containing the project source) on GitHub; -- a set of `.opam` files in [`opam-repository`][opam-repo] that point to this - release archive; -- (optionally) a copy of these `.opam` files in the Tezos - [`opam-repository`][tezos-opam-repo]. +- Git [commit tag][git-tags] +- Set of documentation on GitHub pages (e.g., [`mirage.github.io/irmin`][pages-docs]); +- Release archive (`.tbz` file containing the project source) on GitHub +- Set of `.opam` files in [`opam-repository`][opam-repo] that point to this + release archive +- (Optionally) a copy of these `.opam` files in the Tezos + [`opam-repository`][tezos-opam-repo] Most of this can be handled automatically by [`dune-release`][dune-release], as described in the instructions below. @@ -22,13 +22,13 @@ described in the instructions below. [opam-repo]: https://github.com/ocaml/opam-repository -## Manual benchmarking +## Manual Benchmarking Before releasing, it is important to make sure that the new version doesn't induce performance regressions. The trace replay benchmarks should be used for that purpose. -The performances of individual releases of irmin are saved inside the +The performances of individual releases of Irmin are saved inside the benchmarking server at `/bench/releases/`: ``` . @@ -57,19 +57,19 @@ benchmarking server at `/bench/releases/`: ``` To test a new release, setup an `c3-small-x86-01` Equinix instance, fetch a large -enough replay trace and setup the right versions of the right libraries +enough replay trace, and setup the right versions of the right libraries before running the benchmarks. -The benchmark should be run at least twice (to give insights about the noise), -the two resulting `stat_trace.repr` files should be copied to -`/bench/releases/` using the same naming convention as above. Also set the file +Run the benchmark at least twice (to give insights about the noise). +The two resulting `stat_trace.repr` files should be copied to +`/bench/releases/` using the same naming convention as above. Also, set the file permissions to read-only using `chmod 444 stat_trace.repr`. A run of the benchmark is expected to last \~35min. See [this script](https://github.com/tarides/irmin-tezos/blob/master/bench.sh) for an example of a setup and a bench run. -### Visualising the results +### Visualising the Results A `stat_summary.json` can be computed from a `stat_trace.repr`. @@ -81,8 +81,8 @@ dune exec -- bench/irmin-pack/trace_stats.exe summarise stat_trace.repr >stat_su A conversion is expected to last \~4 min. -One or more summaries can be pretty printed together. The following command -will pretty print both runs of 2 releases side by side: +One or more summaries can be pretty-printed together. The following command +will pretty-print both runs of 2 releases side by side: ```sh ; export ROOT='/bench/releases/ncommits_200k/irmin2.7.0_index1.4.0_repr0.4.0/' ; export ROOT_OLD='/bench/releases/ncommits_200k/irmin2.2.0_index1.2.1/' @@ -95,7 +95,7 @@ will pretty print both runs of 2 releases side by side: See [this script](https://github.com/tarides/irmin-tezos/blob/master/summarise.sh) for an example of a batch conversion to JSON. -## Releasing to opam-repository and GitHub +## Releasing to `opam-repository` and GitHub - Check that no `.opam` files contain `pin-depends` fields. If so, release those packages first. @@ -104,7 +104,7 @@ See [this script](https://github.com/tarides/irmin-tezos/blob/master/summarise.s ; git grep -A 10 "pin-depends" *.opam ``` -- Make a pull-request to this repository containing pre-release changes (drop +- Make a pull request (PR) 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. @@ -134,14 +134,14 @@ See [this script](https://github.com/tarides/irmin-tezos/blob/master/summarise.s 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 +### Recutting a Failed opam Release -It may be necessary to re-cut an attempted release, for instance if the +It may be necessary to recut 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: +tags and reperform the required release steps: ```sh ; git tag -d X.Y.Z # Erase git tag locally @@ -157,7 +157,7 @@ tags and re-perform the required release steps: ; git push -u origin --force # Add new `.opam` files to PR ``` -## Releasing to Tezos' opam-repository +## Releasing to Tezos' `opam-repository` The Tezos project uses [its own `opam-repository`][tezos-opam-repo] to source its dependencies, so upgrading its dependencies requires making a separate @@ -176,7 +176,7 @@ done (The above process is somewhat automated by [this script][tezos-downstream-script].) Once this is done, make an MR to the Tezos -opam-repository and – if necessary – a corresponding MR to Tezos to adjust to +`opam-repository` and, if necessary, a corresponding MR to Tezos to adjust to any API changes. [tezos-opam-repo]: https://gitlab.com/tezos/opam-repository