Releases and versioning¶

Version control and build/packaging. For the checklist that gates a tag, see RELEASING.md.

Version control¶

SemVer (MAJOR.MINOR.PATCH), scoped as described below, not to the raw diff.
main is the default branch; all releases are cut from it. stable-v2.0.0 and stable-v1.0.0 preserve the earlier major lines.
Release versions are Git tags: vMAJOR.MINOR.PATCH (e.g. v2.2.0). No leading v in changelog/released/ filenames (MAJOR.MINOR.PATCH.md, e.g. 2.2.0.md).
Conventional Commits so changelog and release notes stay consistent.

Changelog¶

Unreleased: edit changelog/unreleased.md. make changelog regenerates CHANGELOG.md from changelog/unreleased.md plus changelog/released/*.md.
CHANGELOG.md is generated, never edited: a hand-written section is overwritten by the next make changelog.
Releasing: move unreleased content into changelog/released/<version>.md, then run make changelog again.

Build and package¶

VERSION=1.0.0 make build-release

Builds the server and MCP binaries for your current OS/arch plus checksums.txt; this is a local convenience, not the release matrix.

GitHub release (CI)¶

Pushing a tag v*.*.* triggers release.yml, which runs make generate, builds, and publishes:

Artifact	Platforms / detail
Binary archives	`linux/amd64`, `linux/arm64`, `darwin/arm64`, `darwin/amd64`. Each archive bundles the server, MCP server, `migrate`, the `pqn` tool (`bin/pqn`), the `pqn` extension files (`pqn-extension/`, with `install.sh`), migration files, the built SPA, the entrypoint script, and an example env file
Checksums	`checksums.txt` over the archives
SBOM	`sbom.spdx.json`
Signatures	Every archive, `checksums.txt`, and the SBOM are cosign-signed (Sigstore v0.3 bundles, verify with cosign v3+)
Container image	`ghcr.io/pgquery-narrative/pgquerynarrative:<version>` and `:latest`, `linux/amd64` + `linux/arm64`, built from the root `Dockerfile` with SBOM and provenance attestations, signed and verified by digest
PostgreSQL image with `pqn`	`ghcr.io/pgquery-narrative/pgquerynarrative/pqn-postgres:<16, 17 or 18>` and `:<16, 17 or 18>-<version>`, `linux/amd64` + `linux/arm64`, built from `tools/docker/postgres-pqn.Dockerfile`, signed by digest. The extension is created on first start

There is no separate CLI container image; Dockerfile.cli is not built by release CI. See Supported versions and limits for the same table with Go/Node/PostgreSQL support alongside it.

`pkg/narrative` API stability¶

The embeddable client follows SemVer for its documented public surface:

Surface	Stability	Notes
`narrative.Config`, `NewClient`, `Client.RunQuery`, `GenerateReport`, `GetSchema`, `Close`	Stable	Safe for downstream imports
`narrative.SecurityConfig` fields	Stable	New optional fields may appear in minor releases
`pkg/narrative/middleware` mount helpers	Stable	`MountChi`, `MountGin`, `MountEcho`; use `MountChiSecured`/`WrapSecured` for auth parity
Goa-generated types under `api/gen/`	Unstable	Regenerated from `api/design/`; depend on `pkg/narrative` client methods, not raw Goa types, where possible
`internal/*` packages	Internal	No SemVer guarantee; may change without a major `pkg/narrative` bump

A field removed from a REST response is still a break for anyone generating clients from the published OpenAPI spec, even when pkg/narrative is untouched; it doesn't by itself force a major bump under this table, but it must appear under a ### Breaking heading in the changelog and release notes. v2.1.0 removed ExplainQueryResult.execution_time_ms on exactly these terms, see Evidence and status vocabulary for the replacement fields.

db.RequiredMigrationVersion is a readiness gate, not a startup gate, see Migrations, upgrades, backup. When it moves, release notes must say so and name the version range.

Versioned documentation¶

This site documents the current main only. With a single supported minor line (see SECURITY.md, only the latest minor receives fixes), a version switcher would add navigation overhead without a corresponding second contract to document. Revisit this if the project ever supports more than one line concurrently.