Repository navigation
docs: publish the upgrade policy and mark format-changing releases - #435
Merged
Merged
Conversation
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
force-pushed
the
docs/upgrade-policy
branch
from
November 8, 2026 02:39
448a602 to
a4e2392
Compare
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 indocs/release.md):-alpha,-betaand-rctags 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 andSHA256SUMS. Every release also moveslatestand the installer default, solatestis not a stable channel and the page says to pin a tag or digest./.well-known) follow their specifications.validateBatchFormatsinOpenParquetStore). Goose migrations run forward at startup and have no down path. Rollback means restoring the pre-upgrade backup with the previous binary.Release tooling:
scripts/release-notes.sh(new),release.yml,justfile:verifyjob writes an Upgrade notes section before anything is published. The section is prepended to GitHub's generated changelog withgh release create --notes ... --generate-notes. It compares the tag with the previous published release, fromgh 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:[!CAUTION]Format change: batch format X to Y whenbatchMetadataVersionchanges;[!IMPORTANT]Control schema migration listing the migration files added underinternal/db/migrations;!marker.batchMetadataVersionrecords that dependency; gofmt realigned the constant block.scripts/release-notes_test.shruns underjust 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 setsGIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_NOSYSTEM=1so a contributor's config, hooks and templates take no part.!in the title.Needs owner confirmation
These numbers and choices are proposed defaults:
latestfollows prereleases, as today. Whetherlatest, the installer default and/releases/latestshould follow only stable releases once one exists is a release-workflow change left out of this PR.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 checkpasses locally, includingrelease-test,docs-generate-checkandsite-buildactionlint .github/workflows/release.ymlandshellcheckon both new scriptsscripts/release-notes.shrun 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-alphaGIT_DIRpointing at a scratch repository, leaves that repository unchangedjust test-race: not run; no auth, API, ingest, query, MCP or agent code changedverifyjob now fails if the batch format version cannot be readRefs #430