Repository navigation
refactor!: name the structured query after queries and use last_evaluated_at - #411
Merged
Merged
Conversation
…ated_at The structured query serves dashboards, FanQL, MCP and the builder, so internal/panel becomes internal/query (panel.Query is now query.Spec, PanelTime is TimeOverride, QueryShape is Shape) and the DuckDB layer it displaced moves to internal/engine. The read routes move from /api/panels/* to /api/queries/run, /api/queries/exemplars and /api/queries/variables/resolve with no aliases; clients, authorization, tests and generated docs change together. Alert rules name their last evaluation instant last_evaluated_at like other event instants; a new migration renames the column. Closes #403.
6 of 7 tasks
vishr
added a commit
that referenced
this pull request
Nov 8, 2026
) ## 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 #411 as breaking. It lists #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 - [x] `just check` passes locally, including `release-test`, `docs-generate-check` and `site-build` - [x] `actionlint .github/workflows/release.yml` and `shellcheck` on both new scripts - [x] `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 - [x] The release-notes test, run with `GIT_DIR` pointing at a scratch repository, leaves that repository unchanged - [x] External links checked with lychee - [ ] `just test-race`: not run; no auth, API, ingest, query, MCP or agent code changed - [x] 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
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
Closes #403. Breaking API change; no aliases or fallback routes.
internal/query(wasinternal/panel):panel.Query→query.Spec,PanelTime→TimeOverride,QueryShape→Shape. The DuckDB execution layer moves tointernal/engine.POST /api/panels/query→POST /api/queries/run,/api/panels/exemplars→/api/queries/exemplars,/api/panels/variables/resolve→/api/queries/variables/resolve.Authorization classification, the UI client, e2e and eval harnesses,
and generated API docs change together.
last_eval→last_evaluated_at(JSON and column), through the newmigration
20261030000000_alert_last_evaluated_at.sqlwith its checksum../internal/engine.Verification
just check(pre-push)just test-raceon query, engine, api, mcp, fanql, alert, storejust db-genand storage tests; migration ledger extended