diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..cafd76c --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,51 @@ +# The release of the docs and the Claude Code plugin: on a v* tag (pushed +# by Teg, with urbex-cli's of the same version), a GitHub release with the +# version's notes from CHANGELOG.md - the run fails without them +# (urbforge/redemptor#54) - and a link to the CLI's release. A pre-release +# while urbex is 0.x or the tag has a suffix (v0.1.0-rc.1). +name: release + +on: + push: + tags: ["v*"] + +permissions: + contents: read + +concurrency: + group: release-${{ github.ref }} + cancel-in-progress: false + +jobs: + release: + if: github.repository == 'urbforge/urbex' + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + contents: write # the release + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - name: Publish the release with its notes + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + TAG: ${{ github.ref_name }} + run: | + version=${TAG#v} + plugin=$(sed -n 's/^ *"version": "\(.*\)",$/\1/p' .claude-plugin/plugin.json) + notes=$RUNNER_TEMP/notes.md + { + echo "The docs and the Claude Code plugin ($plugin) of urbex $version." + echo "The CLI, \`urbex-op\` and its image: [urbforge/urbex-cli $TAG](https://github.com/urbforge/urbex-cli/releases/tag/$TAG)." + echo + # The changelog's links are relative to the repository; on the + # release's page they point to this tag's files. + scripts/release-notes.sh "$TAG" | sed "s#](docs/#](https://github.com/$GITHUB_REPOSITORY/blob/$TAG/docs/#g; s#](CHANGELOG.md#](https://github.com/$GITHUB_REPOSITORY/blob/$TAG/CHANGELOG.md#g" + } >"$notes" + case "$TAG" in + v0.* | *-*) pre=--prerelease ;; + *) pre= ;; + esac + gh release create "$TAG" --repo "$GITHUB_REPOSITORY" --verify-tag \ + --title "urbex $version - docs and plugin $plugin" --notes-file "$notes" $pre diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..62eb3c9 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,57 @@ +# Changelog + +What changed in each release of urbforge/urbex: the documentation and +the **Claude Code plugin** (`.claude-plugin`, `skills/`). The format +follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), with +**Breaking** and **Upgrading** sections when a release needs them. + +urbex is tagged together with urbex-cli (`v0.1.0` in both); the CLI, the +`urbex-op` script and its image have their own changelog, in +[urbforge/urbex-cli](https://github.com/urbforge/urbex-cli/blob/main/CHANGELOG.md). + +**The plugin has its own version**, in `.claude-plugin/plugin.json`. It +works with any `urbex` of the same major version; while both are 0.x a +minor may still break, so each plugin version states the minimum `urbex` +it needs (see [Upgrading](docs/upgrading.md#plugin-and-cli-versions)). + +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: the docs install urbex from the +[urbex-cli v0.1.0 release](https://github.com/urbforge/urbex-cli/releases/tag/v0.1.0) +instead of a clone. + +### Plugin 0.2.0 + +Needs **urbex 0.1.0 or later, major 0**. + +- **Added**: the plugin's own version, and its check of `urbex version` + once per session: it says when urbex is older than it needs, or of + another major. +- **Changed**: the `setup` skill downloads `urbex-op` from the newest + release instead of cloning and building urbex-cli; its prerequisites + check reads the image from `urbex-op version`. +- The `setup`, `cli` and `manifest` skills: setting up the platform from + an empty Proxmox node, every `urbex` command with the ones that need + your confirmation, and writing `urbex.yaml`. + +### Docs + +- **Added**: [Upgrading](docs/upgrading.md); `urbex version` in the CLI + reference. +- **Changed**: getting started (with the CLI, Claude Code or another + agent) and the cookbook install from the release; the README says + *preview release* and links the known limitations. + +### Known limitations + +A preview: no backups of the platform yet, Proxmox only, a single +operator. See the [known limitations](docs/known-limitations.md). + +[Unreleased]: https://github.com/urbforge/urbex/compare/v0.1.0...HEAD +[0.1.0]: https://github.com/urbforge/urbex/releases/tag/v0.1.0 diff --git a/README.md b/README.md index e568e1c..39504fd 100644 --- a/README.md +++ b/README.md @@ -247,7 +247,9 @@ Start here: [CLI](docs/getting-started/with-the-cli.md), [any AI agent](docs/getting-started/with-an-ai-agent.md) or [Claude Code](docs/getting-started/with-claude-code.md). -- [**Upgrading**](docs/upgrading.md) — moving to a new release. +- [**Upgrading**](docs/upgrading.md) — moving to a new release; what + changed in each: [`CHANGELOG.md`](CHANGELOG.md) (docs and plugin) and + urbex-cli's [`CHANGELOG.md`](https://github.com/urbforge/urbex-cli/blob/main/CHANGELOG.md). - [**Cookbook**](docs/cookbook.md) — recipes: releasing, rolling back, pinning staging, secrets, adding services, troubleshooting, driving Urbex from an LLM agent (the Claude Code plugin included). diff --git a/docs/upgrading.md b/docs/upgrading.md index fc06d71..af3ee0d 100644 --- a/docs/upgrading.md +++ b/docs/upgrading.md @@ -7,8 +7,10 @@ the tools on your machine. The workspace, the GitOps repo, the platform and your projects stay as they are. While Urbex is 0.x (a preview), a minor release may still change how -something works. **Read the release's notes first**: they say when a -command is needed after upgrading. +something works. **Read the release's notes first** - its GitHub release, +or the `CHANGELOG.md` of [urbex-cli](https://github.com/urbforge/urbex-cli/blob/main/CHANGELOG.md) +and of [this repository](../CHANGELOG.md): their *Breaking* and +*Upgrading* sections say when a command is needed after upgrading. ## With urbex-op diff --git a/scripts/release-notes.sh b/scripts/release-notes.sh new file mode 100755 index 0000000..6c08cb2 --- /dev/null +++ b/scripts/release-notes.sh @@ -0,0 +1,21 @@ +#!/bin/bash +# release-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: release-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 "release-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/tests/plugin-scripts.sh b/tests/plugin-scripts.sh index 433986f..6b78bfb 100755 --- a/tests/plugin-scripts.sh +++ b/tests/plugin-scripts.sh @@ -49,3 +49,15 @@ for arg, want in [ print("ok prepare-proxmox.py parse_host") sys.exit(1 if failed else 0) PY +py_rc=$? + +# The plugin's version has its notes in CHANGELOG.md ("### Plugin X", +# under its release or Unreleased) - urbforge/redemptor#54. +plugin=$(sed -n 's/^ *"version": "\(.*\)",$/\1/p' .claude-plugin/plugin.json) +if grep -q "^### Plugin $plugin\$" CHANGELOG.md; then + echo "ok CHANGELOG.md has plugin $plugin" +else + echo "FAIL CHANGELOG.md has no '### Plugin $plugin' section: add the plugin's notes" >&2 + exit 1 +fi +exit "$py_rc"