diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 0779e28..3714c7a 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -28,6 +28,10 @@ jobs: - uses: jdx/mise-action@236a21c3b91f5db6d4e174b348674a0f0caac06d # v5.2.9 with: install_args: go deno + # A release needs its notes: the tag's version must have a section + # in CHANGELOG.md (urbforge/redemptor#54). Checked first. + - name: Release notes in CHANGELOG.md + run: tools/release/notes.sh "${{ github.ref_name }}" >/dev/null - run: mise run lint - run: mise run test @@ -63,7 +67,24 @@ jobs: [ "$prev" = "$GORELEASER_CURRENT_TAG" ] && prev= export GORELEASER_PREVIOUS_TAG=${prev:-$(git rev-list --max-parents=0 HEAD | tail -n 1)} echo "Releasing $GORELEASER_CURRENT_TAG, changes since $GORELEASER_PREVIOUS_TAG" - goreleaser release --clean + # The release opens with the hand-written notes of the version, + # then GoReleaser's list of commits. + notes=$RUNNER_TEMP/release-header.md + { + version=${GORELEASER_CURRENT_TAG#v} + case "$GORELEASER_CURRENT_TAG" in + v0.* | *-*) echo "urbex $version - a preview release." ;; + *) echo "urbex $version." ;; + esac + echo + tools/release/notes.sh "$GORELEASER_CURRENT_TAG" + echo + echo "## Install" + echo + echo "Download the archive for your system below, check it against \`checksums.txt\`, and put \`urbex\` on your \`PATH\`; or download \`urbex-op\`, which runs \`ghcr.io/urbforge/urbex-op:$version\`. See [getting started](https://github.com/urbforge/urbex/blob/main/docs/getting-started.md), [upgrading](https://github.com/urbforge/urbex/blob/main/docs/upgrading.md) and the [known limitations](https://github.com/urbforge/urbex/blob/main/docs/known-limitations.md). The docs and the Claude Code plugin: [urbforge/urbex $GORELEASER_CURRENT_TAG](https://github.com/urbforge/urbex/releases/tag/$GORELEASER_CURRENT_TAG)." + echo + } >"$notes" + goreleaser release --clean --release-header "$notes" - name: Build provenance of the archives uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2 with: @@ -104,6 +125,8 @@ jobs: tags: ${{ steps.image.outputs.tags }} labels: | org.opencontainers.image.source=https://github.com/${{ github.repository }} + org.opencontainers.image.url=https://github.com/${{ github.repository }}/releases/tag/${{ github.ref_name }} + org.opencontainers.image.documentation=https://github.com/urbforge/urbex/blob/main/docs/getting-started.md org.opencontainers.image.version=${{ steps.image.outputs.version }} org.opencontainers.image.description=urbex and the tools it runs, for urbex-op org.opencontainers.image.licenses=Apache-2.0 diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..31292a1 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,66 @@ +# Changelog + +What changed in each release of urbex-cli: the `urbex` CLI, the +`urbex-op` script and its image `ghcr.io/urbforge/urbex-op`, which are +released together. The format follows +[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), with **Breaking** +and **Upgrading** sections when a release needs them. While urbex is 0.x +a minor release may still change how something works: read Breaking and +Upgrading before you move to it. + +The Claude Code plugin and the docs have their own changelog, in +[urbforge/urbex](https://github.com/urbforge/urbex/blob/main/CHANGELOG.md). +Every release also lists its commits, generated from their titles. + +A pull request that changes what users see adds a line under +*Unreleased*; a release moves them under its version - the release +workflow refuses a tag whose version has no entry here. + +## [Unreleased] + +## [0.1.0] - 2026-11-17 + +The first preview release: urbex as binaries for Linux and macOS (amd64, +arm64) and as `urbex-op` with its published image, instead of a build +from source. + +### Added + +- **The platform**, from an empty Proxmox node, with one command + (`urbex bootstrap`): Gitea for repositories and images, Komodo for + builds and deploys, Technitium for internal DNS, Keycloak for the + applications' users, Grafana, Prometheus and Loki for logs, metrics and + alerts, and a Cloudflare tunnel with Access in front of the admin + tools - or a Quick Tunnel without a Cloudflare account. A prepared LXC + template makes every new machine quick to create. +- **Projects** from an `urbex.yaml`: `urbex apply ` gives each + service its own LXC (or VM, `machine: vm`), staging follows `main` on + every push, `urbex release` and `urbex promote` put the very images + staging ran in production, `urbex deploy` pins or rolls back a version. +- Applications from published images, pinned to their digest; named + volumes and NAS shares; linked applications, which start once what + they use is ready; a PostgreSQL per project, with a role and a schema + per application. +- Configuration and SOPS-encrypted secrets per environment, in the GitOps + repo (`urbex secret`). +- `urbex status` (also `--progress`, `--output json`), `urbex users`, + `urbex doctor`, `urbex discover`, `urbex version`, and progress events + (`--events json`) for programs and the Claude Code plugin. +- `urbex destroy` and `urbex teardown`. +- `urbex-op`: urbex and the tools it runs, in a container, against a + workspace folder; podman or docker, Linux or macOS. + +### Upgrading + +The first release: nothing to upgrade from. A workspace built from a +checkout of urbex-cli works with it; see +[Upgrading](https://github.com/urbforge/urbex/blob/main/docs/upgrading.md). + +### Known limitations + +A preview: no backups of the platform yet, Proxmox only, a single +operator. See the +[known limitations](https://github.com/urbforge/urbex/blob/main/docs/known-limitations.md). + +[Unreleased]: https://github.com/urbforge/urbex-cli/compare/v0.1.0...HEAD +[0.1.0]: https://github.com/urbforge/urbex-cli/releases/tag/v0.1.0 diff --git a/README.md b/README.md index f635554..ccca846 100644 --- a/README.md +++ b/README.md @@ -195,11 +195,16 @@ run test` on GitHub Actions ([`.github/workflows/ci.yml`](.github/workflows/ci.y with Go and Deno from `mise.toml`: run both before you push. The e2e needs a Proxmox node and runs on ours, not in CI. +What changed in each release is in [`CHANGELOG.md`](CHANGELOG.md): a +pull request that changes what users see adds a line under +*Unreleased*, and a release moves them under its version. + A release is a `v*` tag, pushed by a maintainer: [`.github/workflows/release.yml`](.github/workflows/release.yml) runs the tests, then [GoReleaser](https://goreleaser.com) (`.goreleaser.yaml`) builds `urbex` for Linux and macOS (amd64, arm64), with checksums, -provenance and a changelog from the commit titles, and publishes the +provenance, the version's notes from `CHANGELOG.md` (the workflow fails +without them) and the list of commits, and publishes the GitHub release - a pre-release while urbex is 0.x or the tag has a suffix (`v0.1.0-rc.1`). diff --git a/mise.toml b/mise.toml index 97153c0..71038af 100644 --- a/mise.toml +++ b/mise.toml @@ -36,6 +36,7 @@ run = [ "go test ./...", "deno test --no-prompt platform/komodo", "bash tools/operator/test-urbex-op.sh", + "bash tools/release/test-notes.sh", ] [tasks.lint] diff --git a/tools/release/notes.sh b/tools/release/notes.sh new file mode 100755 index 0000000..18bcd1a --- /dev/null +++ b/tools/release/notes.sh @@ -0,0 +1,21 @@ +#!/bin/bash +# notes.sh TAG [CHANGELOG]: the release notes of TAG (v0.2.0, v0.2.0-rc.1) +# from CHANGELOG.md - the section "## [0.2.0] ..." without its heading - +# for the GitHub release. An -rc takes the notes of its version. Fails, +# saying so, when the version has no section or an empty one: a release +# needs its notes (urbforge/redemptor#54). +set -euo pipefail +tag=${1:?usage: notes.sh TAG [CHANGELOG]} +file=${2:-CHANGELOG.md} +version=${tag#v} +version=${version%%-*} +notes=$(awk -v v="$version" ' + /^## \[/ { if (on) exit; on = (index($0, "## [" v "]") == 1); next } + /^\[[^]]+\]: / { next } + on { print } +' "$file" | sed -e '/./,$!d' | sed -e ':a' -e '/^\n*$/{$d;N;ba' -e '}') +if [ -z "$notes" ]; then + echo "notes.sh: $file has no notes for $version: add a '## [$version] - ' section (move the Unreleased lines there)" >&2 + exit 1 +fi +printf '%s\n' "$notes" diff --git a/tools/release/test-notes.sh b/tools/release/test-notes.sh new file mode 100755 index 0000000..f2bd79b --- /dev/null +++ b/tools/release/test-notes.sh @@ -0,0 +1,37 @@ +#!/bin/bash +# Tests of notes.sh (urbforge/redemptor#54). Run by 'mise run test'. +set -u +here=$(cd "$(dirname "$0")" && pwd) +tmp=$(mktemp -d) +trap 'rm -rf "$tmp"' EXIT +cat >"$tmp/CHANGELOG.md" <<'MD' +# Changelog + +## [Unreleased] + +- Something not released yet. + +## [0.2.0] - 2026-12-01 + +### Added + +- A feature. + +## [0.1.0] - 2026-11-17 + +The first one. + +## [0.0.9] - 2026-11-01 + +[0.2.0]: https://example.com/0.2.0 +MD +fails=0 +expect() { # expect NAME WANT GOT + if [ "$2" = "$3" ]; then echo "ok $1"; else echo "FAIL $1: got [$3], want [$2]"; fails=$((fails + 1)); fi +} +expect "a version's section, without its heading" "$(printf '### Added\n\n- A feature.')" "$("$here/notes.sh" v0.2.0 "$tmp/CHANGELOG.md")" +expect "an rc takes its version's notes" "The first one." "$("$here/notes.sh" v0.1.0-rc.3 "$tmp/CHANGELOG.md")" +"$here/notes.sh" v0.3.0 "$tmp/CHANGELOG.md" >/dev/null 2>&1; expect "a version without a section fails" 1 $? +"$here/notes.sh" v0.0.9 "$tmp/CHANGELOG.md" >/dev/null 2>&1; expect "an empty section fails" 1 $? +"$here/notes.sh" v0.1.0 "$here/../../CHANGELOG.md" >/dev/null; expect "the repository's CHANGELOG.md has 0.1.0" 0 $? +[ $fails -eq 0 ] || { echo "$fails failed"; exit 1; }