254 lines
9.8 KiB
Markdown
254 lines
9.8 KiB
Markdown
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.1`. If it is a follow-up release candidate for any
|
||
fixes, we increase digit, e.g. `releases/1.1.0-rc.2`, `releases/1.1.0-rc.3`,
|
||
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:
|
||
|
||
```json
|
||
{"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`][radicle-nix] and
|
||
[`radicle-infra`][radicle-infra] repositories.
|
||
|
||
### Post Changelog
|
||
|
||
<!-- The examples will obviously need a bit of rework, and probably based on -->
|
||
<!-- an upcoming pre-release rather than something historical. /RL -->
|
||
|
||
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].
|
||
|
||
### Release Branch
|
||
|
||
At this point, a release branch should be created. This branch will used for
|
||
*patch releases*, e.g. `1.5.1`, `1.5.2`, etc.
|
||
|
||
The branch must be named `releases/x.y`, similar to the tagged release, where
|
||
`x` is the major version, and `y` is the minor version, e.g `releases/1.5`,
|
||
`releases/1.6`, etc.
|
||
|
||
### CHANGELOG
|
||
|
||
The `heartwood/CHANGELOG.md` must be updated to reflect the latest changes that
|
||
were made with regards to the binaries. Many of them should have been included
|
||
during the development process, such as new features, breaking changes, or fixed
|
||
bugs. It is still worth checking `scripts/changelog` to see if there were any
|
||
missed notes.
|
||
|
||
Once the change log is finalized with a header using the version number, e.g.
|
||
`## 1.5.0`, it should be committed to the `releases/x.y` branch and a patch must
|
||
be made to port the changes to the `master` branch.
|
||
|
||
### Announcement
|
||
|
||
The announcement post is prepared using the [`radicle.xyz`
|
||
repository][radicle-xyz], and should appear in the [Updates][updates] section of
|
||
the website. The announcement is essentially the same as the
|
||
`heartwood/CHANGELOG.md` entry, but should include some preamble about the
|
||
effort of the release – have fun with it!
|
||
|
||
We then announce on [Zulip][zulip], [Mastodon][mastodon], and [Bluesky][bsk].
|
||
|
||
Patch Releases
|
||
--------------
|
||
|
||
After the `x.y.0` release is made, it may be beneficial, or even necessary, to
|
||
release patch releases of the binaries. These patch releases must be compatible
|
||
with minor version that was released, otherwise the commits should not be
|
||
included.
|
||
|
||
These changes may have been made on `master` and back-ported to the
|
||
`releases/x.y` branch. Note that is not the job of the maintainer to ensure that
|
||
the change applies cleanly to both branches – it is the job of the person
|
||
contributing the changes.
|
||
Alternatively, it may be the case that changes are made on the `releases/x.y`
|
||
branch and forward-ported to `master`. The burden of ensuring changes apply
|
||
remains the same as above.
|
||
|
||
Remember that `heartwood/CHANGELOG.md` must be updated to include the latest
|
||
changes in the patch release. These must be forward-ported to the `master`
|
||
branch.
|
||
|
||
[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
|