radicle-heartwood-lfs/RELEASE.md

Release Process

In this document, we describe the release process for the Radicle binaries. It is expected to be a living document as we refine our build and release process.

Pre-Release Process

Before cutting a proper release, we first aim to cut a pre-release so that we can test the binaries on a smaller scale, usually internally. To do this, we follow the following steps, outlined in each subsection.

Tag Version

The first action required is to create a release tag. All tags that start with a releases/ are considered release tags, e.g. releases/1.0.0, releases/1.1.0, releases/1.1.0-rc, etc. Before creating the tag, we must decide which commit we are choosing for the release. In general, this will be the latest commit of the master branch. We checkout this commit:

git checkout <commit>

The tag name that is being chosen for the release candidate is the next semantic version, followed by -rc.0. If it is a follow-up release candidate for any fixes, we increase digit, e.g. releases/1.1.0-rc.1, releases/1.1.0-rc.2, etc.

Note that, for the next part, git config user.signingKey must match the key you are using as your Radicle signing key, and it must be using the ssh format. In your working copy of heartwood you can set this up with the following commands:

git config set gpg.format ssh

git config set user.signingKey "key::$(rad self --ssh-key)""

We provide a script for performing the tagging related options, build/tag. The input to this script does not require the releases/ prefix. For example, if we want to cut a release for releases/1.3.0-rc.3, we would call the script like the following:

build/tag 1.3.0-rc.3

The script will ask you to confirm the creation of the tag, showing you the commit that you're tagging, respond with y if it all looks good.

Run Build

The next thing we do is to build the binaries based on the latest tag. We provide a build/build script that performs the build through a Docker container. The following requirements are needed for running the build script:

• rad
• podman
• sha256sum

Running build/build will find the latest tag and perform the build, this will take some time, so grab a coffee ☕.

---

Note: the script currently outputs warnings about the strip command for MacOS builds. These are ok, and can be ignored.

---

Verify Artifacts

All artifacts constructed from the build/build script will be placed under build/artifacts. Any existing, old artifacts can be removed.

We can then verify the artifacts are present via the build/checksums script, which prints the checksum values of all the binaries that were built, noting that there is a binary for different architectures.

We also check that build/artifacts/radicle.json file to see that the metadata matches what we expected. For example, the output may look something like:

{"name":"rad","version":"1.3.0-rc.3","commit":"3296de8323b5782ff2af9d3a0fe2309a9bf1d3d6","timestamp":"1756131991"}

Making careful note of the version and commit.

Upload Artifacts

The next step is to upload the artifacts to our servers, allowing others to install the binaries, as well as launching the new binaries on our team seed node.

This is achieved through the build/upload script, which requires SSH access to files.radicle.xyz, for example:

SSH_LOGIN=<user> build/upload 1.3.0-rc.3

Once the files are released we can install the binaries via:

curl -O -L https://files.radicle.xyz/releases/latest/radicle-$TARGET.tar.xz

where $TARGET is the relevant architecture and version.

Release on Team Node

To help with testing the pre-release internally, we upgrade our team node, seed.radicle.xyz, which is restricted to only replicate from our team's Node IDs.

We do this using NixOS and the radicle-nix and radicle-infra repositories.

Post Changelog

Once all these steps are completed, we can generate the changelog, by first checking out the relevant tag, and running scripts/changelog – you can also pass a previous version as --from-version. This will output something like the following:

# 👾 Radicle 1.5.0-rc.2

Radicle 1.5.0-rc.2 (7b00bf2e3) is released.

## Installation

```
curl -sSf https://radicle.xyz/install | sh -s -- --no-modify-path --version=1.5.0-rc.2
```

## Notes

* Properly deprecate `rad self --nid` and introduce `rad status --only nid`
* Deprecates `rad diff`
* Obsolete warning for `rad patch review [--patch | --delete]`

## Changelog

This release contains 69 commit(s) by 5 contributor(s).

* `7b00bf2e3` **cli/patch/review: Obsoletion Warning** *<lorenz.leutgeb@radicle.xyz>*
* `8dd17e2a6` **cli/warning: Add `fn obsolete`** *<lorenz.leutgeb@radicle.xyz>*
* `7d1db6a01` **cli/diff: Deprecation Warning** *<lorenz.leutgeb@radicle.xyz>*
* `8558cc223` **cli/self: `--nid` deprecation warning to stderr** *<lorenz.leutgeb@radicle.xyz>*
* `3fb04623a` **cli/warning: Add `fn deprecate`** *<lorenz.leutgeb@radicle.xyz>*
* `2635562c9` **cli/node/status: Add `--only nid`** *<lorenz.leutgeb@radicle.xyz>*
* `8afd55ff6` **build: update release files location** *<fintan.halpenny@gmail.com>*
* `d2e10fdef` **cli/tests/commands: Clean up test `rad_patch`** *<erik@zirkular.io>*
* `19210faab` **protocol/service: Change `Routing table updated..` from info to debug** *<me@sebastinez.dev>*
* `86472fdcc` **remote-helper/fetch: Improve error handling** *<lorenz.leutgeb@radicle.xyz>*
[..]

## Checksums

```
675c9d9731751de9c81f8be5445ac80a5bd6dcc7c5d1718d4d8671b7bdfa69e6  radicle-1.5.0-rc.2-aarch64-unknown-linux-musl.tar.xz
583921069b031789debbd64de86635f0e3e705d742e1e8e619659181b2933c60  radicle-1.5.0-rc.2-aarch64-apple-darwin.tar.xz
fc6ee5d764941aaf21d33547e837f3908fbddba533a5b17675ae04e1ab68a664  radicle-1.5.0-rc.2-x86_64-unknown-linux-musl.tar.xz
166bd82760ac4acf68dc7ba7cfe5f32c490311184def9a387b8e47fd39e28b34  radicle-1.5.0-rc.2-x86_64-apple-darwin.tar.xz
```

Once we have the output from scripts/changelog, we can post to the internal or release candidate topic in Zulip – naming the topic after the release version name. Remember to @all so that everyone is notified. Issues that are encountered should be reported in the Zulip topic, so that they can be resolved for the final release.

In the Notes section we make note of any major or breaking changes that were made in this release.

Here we can define a grace period of how long we wait for the release to be running until we decide to cut the final release, given that there are no issues with the pre-release. This grace period can depend on the size and complexity of the changes.

Release Process

Once the team feels that the release is ready, the final release can be made. The build/tag step should be repeated for the tag, without the -rc suffix. The build/build and build/upload steps are repeated.

Finally, SSH_LOGIN=<user> build/release <version> is used to create a symlink from version release to the latest release – which is used in our install script linked to on [Get Started][website].

The announcement post is prepared using the radicle.xyz repository, and should appear in the Updates section of the website.

We then announce on Zulip, Mastodon, and [Bluesky][bsk].