Files
radicle-explorer/explorer/RELEASE.md
T
Daniel Norman 63a5bb2266 httpd: Make release builds reproducible
- Pin the rust and alpine images by digest
- Check that the rust image matches rust-toolchain
- Install pinned zig 0.17.0 and cargo-zigbuild 0.23.4
- Install cargo-zigbuild before the source copy, to cache it
- Build on linux/arm64 on every host, with docker or podman
- Use 8-character commit IDs and read RADICLE_HTTPD_VERSION
- Name the tagged commit in the announcement, not a build ID
- Link macOS binaries with -dead_strip_dylibs and -rtlib=none
- Move signing out of build into build/sign, which checks checksums
- Fix Dockerfile lint warnings
2026-11-06 10:45:37 +01:00

5.8 KiB

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, set by the release tag. 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.

Versioning

Versions follow semantic versioning. The version covers the HTTP API, the CLI and the config: bump the minor version for additions, and the major version for removals or changes. Before 1.0, 0.y counts as the major, so bump 0.y.z to 0.y.(z+1) for additions and to 0.(y+1).0 for removals or changes. The release tag sets the version; do not change it in Cargo.toml. See ADR 0001 for which releases explorer supports.

Prerequisites

  • Git signing configured via SSH:
    git config set gpg.format ssh
    git config set user.signingKey "$(rad self --ssh-key)"
    
  • Working podman setup (see Podman Setup below)
  • Required tools: podman, rad, sha256sum

Prepare

Normal patches add their highlights to ## Unreleased in CHANGELOG.md. Note in each entry whether the change belongs to radicle-httpd or radicle-search.

Release

  1. Update master:

    git switch master
    git pull --ff-only rad master
    
  2. Make the release commit. The script renames ## Unreleased to the version in CHANGELOG.md and docs/api-changes.md, and adds a new empty ## Unreleased to each:

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

    Check the diff. Then add the API changes from docs/api-changes.md to the new section in CHANGELOG.md. If the release bumps the major, set the target date to drop the previous major in ## Support of docs/api-changes.md, three months from today. Then commit:

    git commit -am "httpd: Release <version>"
    
  3. Make and sign the tag. The script checks the signing key:

    crates/radicle-httpd/build/tag <version>
    
  4. Push the commit and the tag. Push only this tag, not --tags. The push reports that the canonical reference is updated:

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

Build and upload

Do these steps after the tag is canonical.

  1. Check out the tag. The build reads the version from it with git describe:

    git switch --detach releases/httpd/<version>
    
  2. Run the reproducible build. A single run compiles the workspace and packages both binaries, one archive per binary per target. It uses podman; set CONTAINER=docker to use Docker:

    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 .sha256 alongside.

  3. Sign the archives with your Radicle key. This checks each archive against its .sha256 and writes a .sig alongside:

    crates/radicle-httpd/build/sign
    
  4. Upload. This 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

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

  2. Create a new announcement with the following template. <commit> is the 8-character ID of the tagged commit, which the build also writes to radicle-httpd.json: git rev-parse --short=8 'releases/httpd/<version>^{commit}'

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

    Message:

    # 👾 radicle-httpd + radicle-search <version>
    
    `radicle-httpd` and `radicle-search` <version> (<commit>) 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 the <version> section from CHANGELOG.md>
    
    ## 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
  • The build always runs in a linux/arm64 container, with the base images and zig pinned, so that builds on different hosts give the same bytes. It runs natively on Apple silicon, and under emulation on amd64 hosts

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