diff --git a/radicle-httpd/RELEASE.md b/radicle-httpd/RELEASE.md new file mode 100644 index 000000000..12326a4d2 --- /dev/null +++ b/radicle-httpd/RELEASE.md @@ -0,0 +1,132 @@ +# Release Process + +## Prerequisites + +- Git signing configured via SSH: + ```sh + git config set gpg.format ssh + git config set user.signingKey "key::$(rad self --ssh-key)" + ``` +- Working `podman` setup (see [Podman Setup](#podman-setup) below) +- Required tools: `podman`, `rad`, `sha256sum` + +## Prepare Release + +1. Create release branch: + ```sh + git checkout -b releases/ + ``` + +2. Bump version in `radicle-httpd/Cargo.toml` + +3. Update lockfiles: + ```sh + cargo build + ``` + +4. Generate changelog: + ```sh + radicle-httpd/build/changelog >> radicle-httpd/CHANGELOG.md + ``` + +5. Edit changelog and remove irrelevant entries + +6. Commit release: + ```sh + git commit -m "httpd: Release " + ``` + +7. Push for review: + ```sh + 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: +```sh +build/tag +``` + +Publish the tag to Radicle: +```sh +git push rad --tags +``` + +Request delegate approval to make the tag canonical: +```sh +rad sync +git push -f self /tags/releases/:refs/tags/releases/ +``` + +## Build Artifacts + +Run the reproducible build (Linux x86_64 or macOS): +```sh +build/build +``` + +> **Note:** Artifacts are written to `build/artifacts/`. A tagged commit is required; versioning uses `git describe`. + +## Upload Artifacts + +```sh +SSH_LOGIN= 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 ` + + **Message:** + ````markdown + # 👾 radicle-httpd + + `radicle-httpd` () is released. + + ## Installation + + Download binaries from: + - https://files.radicle.xyz/releases/radicle-httpd/ + - https://radicle.xyz/download + + ## Changelog + + + + ## Checksums + + ``` + + ``` + + :info: This release was built on . 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: + +```sh +sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 $USER +podman system migrate +``` diff --git a/radicle-httpd/build/README.md b/radicle-httpd/build/README.md deleted file mode 100644 index 8c37cc9f9..000000000 --- a/radicle-httpd/build/README.md +++ /dev/null @@ -1,77 +0,0 @@ -# Builds - -Radicle uses a [reproducible build][rb] pipeline to make binary verification -easier and more secure. - -[rb]: https://reproducible-builds.org/ - -This build pipeline is designed to be run on an x86_64 machine running Linux. -The output is a set of `.tar.xz` archives containing binaries for the supported -platforms and signed by the user's Radicle key. - -These binaries are statically linked to be maximally portable, and designed to -be reproducible, byte for byte. - -To run the build, simply enter the following command from the repository root: - - build/build - -This will build all targets and place the output in `build/artifacts` with -one sub-directory per build target. - -Note that it will use `git describe` to get a version number for the build. -You *must* have a commit tagged with a version in your history or the build -will fail, eg. `v1.0.0`. -Make sure to create a release commit where you update the `version` field in -the `Cargo.toml` file and tag the commit with a version e.g. `build/tag 0.21.0`. - -When the build completes, the SHA-256 checksums of the artifacts are output. -For a given Radicle version and source tree, the same set of checksums should -always be output, no matter where or when the build is run. If they do not -match, either the build pipeline has a bug, making it non-reproducible, or one -of the machines is compromised. - -Here's an example output for a development version of Radicle: - - b9aa75bba175e18e05df4f6b39ec097414bbf56ccdeb4a2229b557f8b8e05404 radicle-1.0.0-rc.4-3-gb299f3b5-aarch64-apple-darwin.tar.xz - c7070806bf2d17a8a0d3b329e4d57b1e544b7b82cb58e2863074d96348a2ab0d radicle-1.0.0-rc.4-3-gb299f3b5-aarch64-unknown-linux-musl.tar.xz - 1a8327854f16ea90491fb90e0c3291a63c4b2ab01742c8435faec7d370cacb79 radicle-1.0.0-rc.4-3-gb299f3b5-x86_64-apple-darwin.tar.xz - 709ac67541ff0c0c570ac22ab2de9f98320e0cc2cc9b67f1909c014a2bb5bd49 radicle-1.0.0-rc.4-3-gb299f3b5-x86_64-unknown-linux-musl.tar.xz - -A script is included in `build/checksums` to output these checksums after -the artifacts are built. - -Once you have the build artifacts and you have a user on our files.radicle.xyz -you can upload them with the following command. - - SSH_LOGIN= build/upload - -## Requirements - -The following software is required for the build: - - * `podman` - * `rad` (The Radicle CLI) - * `sha256sum` - -## macOS - -macOS binaries are not signed or notarized, so they have to be downloaded via -the CLI to avoid issues. A copy of a small subset of the Apple SDK is included -here to be able to cross-compile. - -## Podman - -We use `podman` to make the build reproducible on any machine by controlling -the build environment. We prefer `podman` to `docker` because it doesn't -require a background process to run and can be run without root access out of -the box. - -The first time you run `podman`, you may have to give yourself some extra UIDs -for `podman` to use, with: - - sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 $USER - -Then update `podman` with: - - podman system migrate