radicle-explorer/RELEASE.md

Release Process

radicle-httpd and radicle-search are released together from this workspace: a single tag, a single changelog, and one build run that produces artifacts for both binaries. They share the same version number, bumped in lockstep. On files.radicle.dev each binary gets its own release folder — releases/radicle-httpd/<version>/ and, as a sibling, releases/radicle-search/<version>/ — so existing radicle-httpd download URLs are unaffected and radicle-search is downloaded independently.

The release tooling lives in crates/radicle-httpd/build/.

Scope

Releases cover only the radicle-httpd and radicle-search binaries. The web front-end (radicle-explorer) is not released this way: it is deployed continuously (rolling release) and must always remain compatible with the latest radicle-httpd/radicle-search release.

Prerequisites

• Git signing configured via SSH:

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

• Working podman setup (see Podman Setup below)
• Required tools: podman, rad, sha256sum

Prepare Release

1. Create release branch:

   git checkout -b release/httpd/<version>
   

2. Bump the version in both crates to the same value, so the two binaries stay coupled:

   • crates/radicle-httpd/Cargo.toml
   • crates/radicle-search/Cargo.toml

3. Update lockfiles:

   cargo build
   

4. Generate changelog (the version is read from crates/radicle-httpd/Cargo.toml):

   crates/radicle-httpd/build/changelog >> CHANGELOG.md
   

5. Edit changelog and remove irrelevant entries. Note in each entry whether a change belongs to radicle-httpd or radicle-search.

6. Commit release:

   git commit -m "Release <version>"
   

7. Push for review:

   git push rad HEAD:refs/patches
   

Review & Merge

1. Wait for delegate approvals
2. Merge patch into master

Tag Release

Create and sign the release tag (one tag covers both binaries):

crates/radicle-httpd/build/tag <version>

Publish the tag to Radicle. Push only this tag: every tag under releases/ that a delegate pushes becomes canonical, so --tags would also publish any stray local ones.

git push rad refs/tags/releases/httpd/<version>
rad sync

Build Artifacts

Run the reproducible build (Linux x86_64 or macOS). A single run compiles the workspace and packages both binaries — one archive per binary per target:

crates/radicle-httpd/build/build

This writes to crates/radicle-httpd/build/artifacts/:

• radicle-httpd-<version>-<target>.tar.xz (binary + man page)
• radicle-search-<version>-<target>.tar.xz (binary)

each with a .sig and .sha256 alongside.

Note: A tagged commit is required; versioning uses git describe.

Upload Artifacts

The upload publishes each binary into its own sibling folder on files.radicle.dev and creates the version-less and latest symlinks for both:

SSH_LOGIN=<username> crates/radicle-httpd/build/upload

Warning: Uploading immediately publishes the release.

Announce Release

1. Mark the previous release as resolved in Zulip #Announcements

2. Create a new announcement with the following template:

   Topic: radicle-httpd + radicle-search <version>

   Message:

   # 👾 radicle-httpd + radicle-search <version>
   
   `radicle-httpd` and `radicle-search` <version> (<build-id>) are released.
   
   ## Installation
   
   Download binaries from:
   - https://files.radicle.dev/releases/radicle-httpd/<version>
   - https://files.radicle.dev/releases/radicle-search/<version>
   - https://radicle.dev/download
   
   ## Changelog
   
   <copy output from crates/radicle-httpd/build/changelog>
   
   ## Checksums
   
   ```
   <copy output from crates/radicle-httpd/build/checksums>
   ```
   
   :info: This release was built on <platform>. Build reproducibility across platforms is unsupported; checksums may differ if rebuilt elsewhere.
   

Notes

Important:

• macOS binaries are unsigned and not notarized; download via CLI only
• Build reproducibility across platforms is not guaranteed

Podman Setup

We use podman for reproducible builds across machines. It's preferred over Docker because it runs without a daemon and doesn't require root access.

On first run, you may need to configure UID/GID ranges:

sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 $USER
podman system migrate