How Queen ships

A release touches the broker image, five client SDKs and the CLI, across five package registries plus GitHub Releases. Two of those channels are published by CI on a trigger; the rest are published by a person running a command. Knowing which is which is the point of this page.

Where the version lives

server/server.json is the single source. Three separate things read it:

• server/build.rs extracts version and exports it as QUEEN_VERSION, which is what GET /health, the boot log and queenctl ping report. A version bump therefore forces a rebuild of the broker.
• build.sh uses name and version to tag and push the image locally.
• .github/workflows/docker-build.yml reads both with jq for the same purpose in CI.

Everything else carries its own version, or none at all.

The versioning rule

The broker and the SDKs are version-aligned at 1.0.0. One MAJOR.MINOR.PATCH for the broker image, npm, PyPI, Packagist, the Go module tag and the CLI tag, so a client version tells you which broker it was released against without a compatibility matrix.

What CI publishes

The container images

.github/workflows/docker-build.yml publishes two images to GHCR, as a matrix over the two Dockerfiles:

Both build for linux/amd64 and linux/arm64 from the repository root: the proxy crate embeds ../server/webapp/dist, so its context cannot be proxy/. Each gets three tags: its own version, sha-<short>, and latest. The broker also receives QUEENCTL_VERSION and QUEENCTL_COMMIT as build arguments so that queenctl version inside the container matches what the broker reports.

Authentication is the workflow’s own GITHUB_TOKEN under permissions: packages: write, so there are no registry secrets to rotate. Layer caching is the GitHub Actions cache, scoped per image (scope=${{ matrix.image }}); a shared scope would make the two matrix legs evict each other’s layers and cold-build every run.

Triggers are a push to the release branch, a v* tag, or workflow_dispatch. A pull request against release builds both images without pushing.

The CLI

.github/workflows/release-cli.yml fires on a tag matching clients/client-cli/v* and runs GoReleaser v2, which cross-compiles queenctl for linux, darwin and windows on amd64 and arm64 (windows/arm64 excluded), produces tar.gz archives (zip on windows) with checksums and pre-built shell completions, and attaches them to a GitHub Release. Version, commit and build date go in through -ldflags, so queenctl version reports the tag.

The directory-prefixed tag shape is required by Go’s module proxy for a nested module, and GoReleaser wants bare semver, so the workflow strips the prefix into GORELEASER_CURRENT_TAG and runs with --skip=validate. The bare semver tag does not physically exist at the release commit, only the prefixed one does.

What a human publishes

Four channels have no workflow. Each needs a command run by a maintainer.

The C++ client needs nothing published: consumers take clients/client-cpp/queen_client.hpp at the tag.

Two tag shapes are load-bearing and easy to get wrong. Both nested Go modules need the directory-prefixed form (clients/client-go/v1.0.0 and clients/client-cli/v1.0.0) because that is how Go’s module proxy resolves a module that is not at the repository root. Without the prefix, go get reports no matching versions. The tags already in the repository follow both shapes, alongside the plain vX.Y.Z broker tags.

Order

The broker tag and image go first, because every SDK is released against a broker; then npm, because most downstream consumers wait on it; then PyPI; then the Go module tag; then the plain vX.Y.Z tag that Packagist and the C++ header hang off; then the CLI tag, which triggers its own workflow.

Rollback, and the one place additivity stops

Schema application is idempotent by construction. server/src/schema.rs applies schema.sql and all 34 stored-procedure files at every boot, in lexical order, under a session advisory lock, and every statement is CREATE OR REPLACE, IF NOT EXISTS or ADD COLUMN IF NOT EXISTS. So re-applying is always safe, and rolling the broker image back to a previous 1.x is safe at the database level.

There is one hard exception, and it is the boundary into 1.0. server/sql/procedures/040_log_drop_legacy.sql runs before the log-engine schema and drops the retired seg_* engine: every queen.seg_* function, discovered dynamically over pg_proc so no straggler survives, then the legacy tables, then the seg-era columns folded into queen.partition_consumers. It is written to be a no-op on a database that never had them and a full teardown on one that did.

What the older release note gets wrong

developer/14-release.md is the pre-1.0 checklist and is still in the tree. Read it for the publishing mechanics of npm, PyPI and Packagist, which are unchanged. Everything below it says no longer holds.

One workflow is dead in the same way. .github/workflows/cpp-server-build.yml triggers on the release branch and runs make deps and make build-only in server/, targets that were removed with the C++ broker; it cannot succeed. And .github/workflows/cli.yml pins its end-to-end broker to smartnessai/queen-mq:0.14.3, so the CLI’s end-to-end suite currently tests against a pre-log-engine broker.

Post-release

• Smoke-test the published packages from a clean directory rather than a local link: install queen-mq from npm and from PyPI, and go get the client module at the new version.
• Write release notes covering schema changes, new environment variables and anything removed. A removed route or environment variable is a major-version change.
• Re-check that the published image tag in these docs matches what was pushed. It appears in Start here and Self-hosting.