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

`v` are considered release tags, e.g. `v1.0.0`, `v1.1.0`, `v1.1.0-pre`, 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>

```

<!-- TODO: I'd prefer -rc, -rc1, -rc2, etc. -->

The tag name that is being chosen for the pre-release is the next semantic

version, followed by `-pre.0`. If it is a follow-up pre-release for any fixes,

we append a `.` and digit, e.g. `v1.1.0-pre.1`, `v1.1.0-pre.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 `v` prefix. For example, if we

want to cut a release for `v1.1.0-pre`, we would call the script like the

following:

```

build/tag 1.1.0-pre

```

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 a few minutes, 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:

```json

{"name":"rad","version":"1.1.0-pre","commit":"0c9a7419","timestamp":"1729696767"}

```

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`.

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`][radicle-nix] and

[`radicle-infra`][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 v1.1.0-pre

Radicle v1.1.0-pre (f7d8f1b8) is released.

## Installation

```

curl -sSf https://radicle.xyz/install | sh -s -- --no-modify-path --version=1.1.0-pre

```

## Notes

* This update is recommended for everyone. No manual intervention is required.

## Changelog

* `f7d8f1b8` **radicle: Distinguish seeding policy types** *<cloudhead@radicle.xyz>*

* `bbb292c8` **node: Don't panic on connection logic error** *<cloudhead@radicle.xyz>*

## Checksums

```

7f0d99609915d28b4333185e42ff14442b9c5d2ec463d3f5f327fe8bb56145ac  radicle-v1.1.0-pre-x86_64-unknown-linux-musl.tar.xz

7d197c8f0a8ab5837610913a1372b9f66214dbd402fed8def65aa6983f01545e  radicle-v1.1.0-pre-x86_64-apple-darwin.tar.xz

312700ca44f0fa1234687819d29426e83509f0663051779a8908fb0c5e3708e4  radicle-v1.1.0-pre-aarch64-apple-darwin.tar.xz

059eaf77539821a5a9e3e82df9fc5f076aca3ca269c80274251c388af6508be3  radicle-v1.1.0-pre-aarch64-unknown-linux-musl.tar.xz

```

~~~

Once we have the output from `scripts/changelog`, we can post to the internal or

pre-release 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 `-pre` suffix.

The `build/build` and `build/upload` steps are repeated.

Finally, `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][radicle-xyz], and should appear in the [Updates][updates] section of

the website.

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

[radicle-infra]: https://app.radicle.xyz/nodes/seed.radicle.xyz/rad:z254T5p17bdFPmzfDojsdjo4HjpoZ

[radicle-nix]: https://github.com/radicle-nix/radicle-nix

[get-started]: https://radicle.xyz/#get-started

[radicle-xyz]: https://app.radicle.xyz/nodes/seed.radicle.xyz/rad:z371PVmDHdjJucejRoRYJcDEvD5pp

[updates]: https://radicle.xyz/#updates

[zulip]: https://radicle.zulipchat.com/#narrow/channel/409174-announcements

[mastodon]: https://toot.radicle.xyz/explore

[bsky]: https://bsky.app/profile/radicle.xyz