RELEASE: Add file documenting the release process
Add a `RELEASE.md` file to document and track the release process of the `heartwood` binaries.
This commit is contained in:
Fintan Halpenny
Lorenz Leutgeb
parent
e63c30976e
commit
1c9a1b4fcb
|
|
@ -0,0 +1,208 @@
|
||||||
|
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:
|
||||||
|
|
||||||
|
```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].
|
||||||
|
|
||||||
|
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
|
||||||
Loading…
Reference in New Issue