Skip to content

docs: publish the upgrade policy and mark format-changing releases - #435

Merged
vishr merged 5 commits into
mainfrom
docs/upgrade-policy
Nov 8, 2026
Merged

vishr merged 5 commits into
mainfrom
docs/upgrade-policy

Conversation

@vishr

@vishr vishr commented Nov 8, 2026 •

Copy link
Copy Markdown
Member

What changed

This PR covers the policy part of #430. It publishes an upgrade policy on the docs site and makes the release workflow mark format-changing releases in their notes.

Upgrade policy (site/src/content/docs/docs/guides/upgrade.mdx, summarized in docs/release.md):

  • Channels. A CalVer tag with no suffix is stable. -alpha, -beta and -rc tags are prereleases. No stable release exists yet. Every release, of either channel, ships the same assets: archives, SHA256SUMS, and build-provenance attestations for the archives and SHA256SUMS. Every release also moves latest and the installer default, so latest is not a stable channel and the page says to pin a tag or digest.
  • Breaking-change notice. A prerelease may break in any release, without notice. A stable release must announce a breaking change in an earlier stable release's notes at least 30 days before a stable release ships it.
  • Route and API deprecation. Deprecation is a notice, not an overlap window. This follows the existing AGENTS.md rule: no aliases or fallback, and a rename updates registrations, clients and generated reference in one release. The deprecated contract keeps working unchanged until the release that is announced to remove it. Protocol-defined contracts (OTLP, MCP protocol, OAuth, /.well-known) follow their specifications.
  • Restore. A backup is restored only with the version that created it, because nothing in the data directory records which release wrote it. A release reads only its own batch format and refuses to start on any other (validateBatchFormats in OpenParquetStore). Goose migrations run forward at startup and have no down path. Rollback means restoring the pre-upgrade backup with the previous binary.
  • Skipping releases works for control migrations, which apply in order. Read the notes of every skipped release.

Release tooling: scripts/release-notes.sh (new), release.yml, justfile:

  • The tag workflow's verify job writes an Upgrade notes section before anything is published. The section is prepended to GitHub's generated changelog with gh release create --notes ... --generate-notes. It compares the tag with the previous published release, from gh release list --exclude-drafts, which the workflow passes on stdin. A tag whose release failed has no release, such as v2026.10.21-alpha, so it is skipped and the next published release reports its changes. The section emits:
    • a [!CAUTION] Format change: batch format X to Y when batchMetadataVersion changes;
    • an [!IMPORTANT] Control schema migration listing the migration files added under internal/db/migrations;
    • otherwise, a Storage: unchanged line, so a missing marker is never ambiguous;
    • a Breaking changes list of commit subjects with the Conventional Commits ! marker.
  • The script fails the release if it cannot read the format version, so a format change is never published unmarked. A comment on batchMetadataVersion records that dependency; gofmt realigned the constant block.
  • Run against real history, it marks v2026.11.0-alpha as format 4 to 5 with 3 migrations and refactor!: name the structured query after queries and use last_evaluated_at #411 as breaking. It lists feat(auth)!: one bearer secret format and the foi_ ingest prefix #424 as breaking for v2026.11.1-alpha, and reports storage unchanged for v2026.11.2-alpha.
  • scripts/release-notes_test.sh runs under just release-test. It builds a throwaway repository and covers a skipped, unpublished tag. It clears Git's hook environment (git rev-parse --local-env-vars) first so it cannot touch the repository that runs the hook, and sets GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_NOSYSTEM=1 so a contributor's config, hooks and templates take no part.
  • The PR template asks breaking or batch-format changes to carry ! in the title.

Needs owner confirmation

These numbers and choices are proposed defaults:

  1. 30-day notice for breaking changes between stable releases. It is measured from the announcing stable release, and the change must land in a later release.
  2. No overlap window. Deprecation stays notice-only to keep the no-alias rule. If you want old and new routes to coexist for a period, AGENTS.md's "add no aliases or fallback behavior" rule needs an amendment.
  3. No security exemption is written. If you want urgent security fixes to skip the notice period, it should be stated.
  4. latest follows prereleases, as today. Whether latest, the installer default and /releases/latest should follow only stable releases once one exists is a release-workflow change left out of this PR.
  5. Comparison baseline. The markers compare each release with the previous published release of either channel. A stable release that follows several prereleases is not compared with the previous stable release. The page tells stable-only users to read every skipped release's notes. Generating a cumulative stable-to-stable section is possible if you want it.
  6. Draft releases. Drafts are excluded from the baseline, so a release whose draft was never published is skipped like a failed tag. Whether drafts should ever count is your call.

Not in this PR

Cutting the first stable (non-prerelease) tag is the owner's step. This PR cuts no tag and publishes no release. Once a stable tag ships, the remaining acceptance criterion is met by the existing workflow, which already publishes checksums and attestations.

Verification

  • just check passes locally, including release-test, docs-generate-check and site-build
  • actionlint .github/workflows/release.yml and shellcheck on both new scripts
  • scripts/release-notes.sh run against v2026.10.24-alpha through v2026.11.2-alpha, and against v2026.10.22-alpha with the published release list. It compares with v2026.10.20-alpha and skips the unpublished v2026.10.21-alpha
  • The release-notes test, run with GIT_DIR pointing at a scratch repository, leaves that repository unchanged
  • External links checked with lychee
  • just test-race: not run; no auth, API, ingest, query, MCP or agent code changed
  • Release-contract change called out: release notes gain a generated section, and the verify job now fails if the batch format version cannot be read

Refs #430

vishr added 2 commits November 7, 2026 18:29
Operators need to know which releases are stable, how much notice a breaking
change gets, and which releases drop or migrate stored data before they pin a
version. The upgrade guide now states the release channels, the notice period
for breaking changes, the route and API deprecation rules, and that a backup
is restored only with the version that created it.

The release notes so far mark format changes by hand. scripts/release-notes.sh
now writes an "Upgrade notes" section for every release in the tag workflow's
verify job, before anything is published. It compares the tag with the
previous release tag and marks a batch format change, added control
migrations, and `!` breaking changes, and it fails the release if it cannot
read the batch format version.

Refs #430
A tag whose release workflow failed, such as v2026.10.21-alpha, has no GitHub
Release. Comparing with it would report a format change it introduced as
unchanged in the next release. The workflow now passes the non-draft release
tags from `gh release list` on stdin, and the script fails if that previous tag
is not fetched.

The test also ignores global and system Git configuration. The upgrade guide
no longer claims a version's image tag cannot be re-pushed, drops sentences
that would go stale, and states that image tags omit the leading `v`.

Refs #430
@vishr
vishr force-pushed the docs/upgrade-policy branch from 448a602 to a4e2392 Compare November 8, 2026 02:39
vishr added 3 commits November 7, 2026 19:10
An empty or truncated `gh release list` result made every release look like
the first, silently dropping its format, migration and breaking-change
markers. The script now fails when no published release precedes the tag but
git holds an older release tag.

Refs #430
@vishr
vishr merged commit 7a259a0 into main Nov 8, 2026
19 checks passed
@vishr
vishr deleted the docs/upgrade-policy branch November 8, 2026 04:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant