From 535a55c660564726afb1ff81fcfb0399d492aba7 Mon Sep 17 00:00:00 2001 From: John Mitsch Date: Thu, 11 Jun 2026 15:02:19 -0400 Subject: [PATCH] docs(release): document .deb install and curate release-notes install block (DX-5675) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README install section reordered around one recommended path per platform — Homebrew (macOS/Linux), Scoop (Windows), .deb (Debian/Ubuntu), AUR (Arch), COPR (Fedora/EPEL), Docker (GHCR) — with crates.io / source / prebuilt binaries grouped under an Alternatives subsection. The .deb, COPR, and Docker entries are new; the others are kept verbatim. Adds a `release-update-install-notes` justfile recipe that prepends a curated "How to install" block (rendered from a reviewable template at packaging/release-notes-install.md.tmpl, with {{VERSION}} substitution) to the GitHub release body. cargo-dist's auto-generated install section is preserved below a `---` separator. The block is bracketed by HTML-comment markers so re-runs replace the existing block instead of stacking, making the recipe safe to invoke standalone or as the final step of `release-sync-manual-channels`, which it now is. --- Justfile | 53 ++++++++++++++++++++++++- README.md | 51 ++++++++++++++++++++---- RELEASING.md | 11 +++++ packaging/release-notes-install.md.tmpl | 52 ++++++++++++++++++++++++ 4 files changed, 158 insertions(+), 9 deletions(-) create mode 100644 packaging/release-notes-install.md.tmpl diff --git a/Justfile b/Justfile index e20798e..faf8448 100644 --- a/Justfile +++ b/Justfile @@ -264,6 +264,55 @@ release-update-scoop-bucket version bucket_path: echo "Committed qn {{version}} to {{bucket_path}}. To publish:" echo " git -C {{bucket_path}} push" +# Prepend a curated "How to install" section to the GitHub release body for +# v. The block is rendered from packaging/release-notes-install.md.tmpl +# (substituting {{VERSION}}) and bracketed by HTML-comment markers so re-runs +# replace the existing block instead of stacking duplicates. cargo-dist's +# auto-generated body is preserved below a `---` separator. +# +# Usage: +# just release-update-install-notes 0.1.8 # edits the release +# just release-update-install-notes 0.1.8 --dry-run # prints assembled body to stdout +release-update-install-notes version mode="": + #!/usr/bin/env bash + set -euo pipefail + version="{{version}}" + mode="{{mode}}" + if [[ -n "$mode" && "$mode" != "--dry-run" ]]; then + echo "Error: unknown mode '$mode' (expected --dry-run or unset)." >&2 + exit 1 + fi + tmpl="packaging/release-notes-install.md.tmpl" + if [[ ! -f "$tmpl" ]]; then + echo "Error: $tmpl not found." >&2 + exit 1 + fi + rendered=$(sed "s/{{ '{{' }}VERSION{{ '}}' }}/${version}/g" "$tmpl") + start_marker='' + end_marker='' + # The block itself does not include the `---` separator — the separator lives + # between the block and the rest of the body and stays in the body across re-runs. + block=$(printf '%s\n%s\n%s' "$start_marker" "$rendered" "$end_marker") + current=$(gh release view "v${version}" --json body --jq .body) + if [[ "$current" == *"$start_marker"* && "$current" == *"$end_marker"* ]]; then + # Replace existing block (idempotent re-run). Split body around markers in pure bash. + before="${current%%$start_marker*}" + after_with_end="${current#*$start_marker}" + after="${after_with_end#*$end_marker}" + new_body="${before}${block}${after}" + else + new_body=$(printf '%s\n\n---\n%s' "$block" "$current") + fi + if [[ "$mode" == "--dry-run" ]]; then + printf '%s\n' "$new_body" + exit 0 + fi + tmpfile=$(mktemp) + trap 'rm -f "$tmpfile"' EXIT + printf '%s\n' "$new_body" > "$tmpfile" + gh release edit "v${version}" --notes-file "$tmpfile" + echo "Updated release v${version} with curated install block." + # Run release-update-{homebrew-tap,scoop-bucket,aur-bin} in sequence for # the latest release tag, then print the three `git push` commands the # maintainer needs to run to publish. Auto-detects the version from the @@ -307,7 +356,9 @@ release-sync-manual-channels root="~/qn" version="": echo just release-update-aur-bin "$version" "${root}/qn-bin" echo - echo "All three channels updated. To publish, run:" + just release-update-install-notes "$version" + echo + echo "Manual channels and release-notes install block updated. To publish, run:" echo " git -C ${root}/homebrew-tap push" echo " git -C ${root}/scoop-bucket push" echo " git -C ${root}/qn-bin push" diff --git a/README.md b/README.md index 3123533..f51ecb2 100644 --- a/README.md +++ b/README.md @@ -29,13 +29,7 @@ error: null ## Installation -### From crates.io - -```sh -cargo install quicknode-cli -``` - -The crate name is `quicknode-cli` but the installed binary is `qn`. +Pick the recommended path for your platform. Other channels are listed under [Alternatives](#alternatives). ### Homebrew (macOS, Linux) @@ -50,19 +44,60 @@ scoop bucket add quicknode https://github.com/quicknode/scoop-bucket scoop install quicknode/qn ``` +### `.deb` (Debian, Ubuntu) + +Each GitHub release attaches `qn__amd64.deb` and `qn__arm64.deb`. Check your architecture with `dpkg --print-architecture`, then grab the matching file from the [latest release page](https://github.com/quicknode/cli/releases/latest): + +```sh +# replace with the version on the release page, e.g. 0.1.8 +curl -LO https://github.com/quicknode/cli/releases/download/v/qn__amd64.deb +sudo apt install ./qn__amd64.deb +``` + ### Arch Linux (AUR) ```sh yay -S qn-bin # or any other AUR helper ``` -### From source +### Fedora, EPEL (COPR) + +```sh +sudo dnf copr enable quicknode/qn +sudo dnf install qn +``` + +### Docker (GHCR) + +```sh +docker pull ghcr.io/quicknode/qn:latest +docker run --rm ghcr.io/quicknode/qn:latest --help +``` + +### Alternatives + +
+crates.io, from source, prebuilt binaries + +**crates.io:** + +```sh +cargo install quicknode-cli +``` + +The crate name is `quicknode-cli` but the installed binary is `qn`. + +**From source:** ```sh git clone git@github.com:quicknode/cli.git && cd cli cargo install --path . ``` +**Prebuilt binaries:** every GitHub release attaches per-platform archives — see the [latest release page](https://github.com/quicknode/cli/releases/latest). + +
+ ## Authentication You will need a Quicknode API key to get started. Once you have that, you can run `qn auth login` diff --git a/RELEASING.md b/RELEASING.md index 4314ec5..609c41a 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -76,6 +76,17 @@ git -C ~/qn/qn-bin push The recipe pulls both Linux gnu sha256 sidecars (x86_64 + aarch64) from the release, renders a `PKGBUILD` + `.SRCINFO`, and stages them. Push goes to `ssh://aur@aur.archlinux.org/qn-bin.git` — the AUR's git remote. +### Curated install block on the release notes + +`release-sync-manual-channels` finishes by calling `release-update-install-notes`, which prepends a curated "How to install" section to the GitHub release body. Source for the block is `packaging/release-notes-install.md.tmpl`; edit it there if the install copy needs to change. The recipe is idempotent — re-running against the same release replaces the existing block rather than stacking duplicates — so it's safe to invoke standalone: + +```fish +just release-update-install-notes X.Y.Z # edits the release in place +just release-update-install-notes X.Y.Z --dry-run # prints the assembled body without editing +``` + +cargo-dist's auto-generated content is preserved below a `---` separator. + ## One-time setup notes A few channels needed manual setup the first time. Captured here so the next maintainer doesn't have to rediscover them. diff --git a/packaging/release-notes-install.md.tmpl b/packaging/release-notes-install.md.tmpl new file mode 100644 index 0000000..3ca7bbd --- /dev/null +++ b/packaging/release-notes-install.md.tmpl @@ -0,0 +1,52 @@ +## Install + +Pick the recommended path for your platform. + +### Homebrew (macOS, Linux) + +```sh +brew install quicknode/tap/qn +``` + +### Scoop (Windows) + +```powershell +scoop bucket add quicknode https://github.com/quicknode/scoop-bucket +scoop install quicknode/qn +``` + +### `.deb` (Debian, Ubuntu) + +Check your architecture with `dpkg --print-architecture`, then grab the matching `.deb` asset from this release: + +```sh +# amd64 +curl -LO https://github.com/quicknode/cli/releases/download/v{{VERSION}}/qn_{{VERSION}}_amd64.deb +sudo apt install ./qn_{{VERSION}}_amd64.deb + +# arm64 +curl -LO https://github.com/quicknode/cli/releases/download/v{{VERSION}}/qn_{{VERSION}}_arm64.deb +sudo apt install ./qn_{{VERSION}}_arm64.deb +``` + +### Arch Linux (AUR) + +```sh +yay -S qn-bin # or any other AUR helper +``` + +### Fedora, EPEL (COPR) + +```sh +sudo dnf copr enable quicknode/qn +sudo dnf install qn +``` + +### Docker (GHCR) + +```sh +docker pull ghcr.io/quicknode/qn:{{VERSION}} +docker run --rm ghcr.io/quicknode/qn:{{VERSION}} --help +``` + +For `cargo install`, source builds, and raw prebuilt binaries see the [project README](https://github.com/quicknode/cli#alternatives).