From 2b0ba97de19683ee9bd17a846f89c13aeabc3c03 Mon Sep 17 00:00:00 2001 From: Vishal Rana Date: Sun, 8 Nov 2026 16:52:06 -0800 Subject: [PATCH 1/2] feat(release): graduate releases to the stable channel Remove the alpha maturity from the release script so the next tag has no suffix, and stop describing Fanout as alpha. The upgrade policy's 30-day notice now covers shipped capabilities. Preview capabilities can still change in any release, with the change marked in the upgrade notes. --- README.md | 2 +- docs/release.md | 2 +- scripts/release.sh | 2 +- scripts/release_test.sh | 20 +++++++++---------- .../content/docs/docs/get-started/install.mdx | 5 +++-- .../docs/docs/get-started/overview.mdx | 3 ++- site/src/content/docs/docs/guides/upgrade.mdx | 17 ++++++++++------ .../docs/docs/reference/capabilities.mdx | 5 +++-- 8 files changed, 32 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index a271bb9a3..246c8182a 100644 --- a/README.md +++ b/README.md @@ -212,7 +212,7 @@ generated assets, hooks, and project layout. ## Releases Versions are CalVer — `vYYYY.M.N[-alpha|-beta|-rc]`, numbered from 0 within each month across all -maturity suffixes. Fanout is alpha (for example, `v2026.11.0-alpha`); GA has no suffix. +maturity suffixes (for example, `v2026.11.0-alpha`). A stable release has no suffix. Container tags omit the leading `v`, and every release moves `latest`. Tagged releases publish identical manifests to Docker Hub (`labstack/fanout`) and GHCR (`ghcr.io/labstack/fanout`); GHCR is canonical and also carries development images. diff --git a/docs/release.md b/docs/release.md index f786464b6..663d85035 100644 --- a/docs/release.md +++ b/docs/release.md @@ -15,7 +15,7 @@ Fanout publishes one release from a verified commit on `main`. A release contain Tags use unpadded CalVer: `vYYYY.M.N[-alpha|-beta|-rc]`. The suffix states product maturity; GA has no suffix. The first release in a month is `.0`, and every -release increments `N` regardless of suffix. Fanout is alpha. For example, +release increments `N` regardless of suffix. For example, `v2026.10.1-alpha` follows `v2026.10.0-alpha`. Container tags omit the leading `v`, so `v2026.10.1-alpha` publishes `ghcr.io/labstack/fanout:2026.10.1-alpha` and `labstack/fanout:2026.10.1-alpha`. diff --git a/scripts/release.sh b/scripts/release.sh index 157f88388..48b4c0914 100755 --- a/scripts/release.sh +++ b/scripts/release.sh @@ -2,7 +2,7 @@ set -euo pipefail # Change product maturity (alpha, beta, rc, or empty for GA) when the product graduates. -readonly PRODUCT_MATURITY=alpha +readonly PRODUCT_MATURITY= die() { printf 'release: %s\n' "$1" >&2 diff --git a/scripts/release_test.sh b/scripts/release_test.sh index e7fa5341b..b87e4f932 100644 --- a/scripts/release_test.sh +++ b/scripts/release_test.sh @@ -31,12 +31,12 @@ assert_next_tag() ( ) test_next_release_tags() { - assert_next_tag first-of-month v2026.10.0-alpha $'v2026.9.12-alpha\nv2025.10.4\nv2026.11.3-rc' - assert_next_tag bare-tag v2026.10.1-alpha v2026.10.0 - assert_next_tag suffixed-tags v2026.10.3-alpha $'v2026.10.0-alpha\nv2026.10.1-alpha\nv2026.10.2-alpha' - assert_next_tag mixed-suffixes v2026.10.5-alpha $'v2026.10.3-rc\nv2026.10.1-beta\nv2026.10.4\nv2026.10.2-alpha' - assert_next_tag numeric-order v2026.10.11-alpha $'v2026.10.9-rc\nv2026.10.10-alpha\nv2026.10.2-beta' - assert_next_tag malformed-tags v2026.10.1-alpha $'v2026.10.0\nv2026.10.01-alpha\nv2026.10.90-preview\nv2026.10.91-alpha.1\nv2026.10.92-ALPHA\nv2026.10.93-extra\nv2026.10.94.0\nv2026.010.95\nv2026x10.96\nv2026.10.-1\n2026.10.97\nv20260.10.98' + assert_next_tag first-of-month v2026.10.0 $'v2026.9.12-alpha\nv2025.10.4\nv2026.11.3-rc' + assert_next_tag bare-tag v2026.10.1 v2026.10.0 + assert_next_tag suffixed-tags v2026.10.3 $'v2026.10.0-alpha\nv2026.10.1-alpha\nv2026.10.2-alpha' + assert_next_tag mixed-suffixes v2026.10.5 $'v2026.10.3-rc\nv2026.10.1-beta\nv2026.10.4\nv2026.10.2-alpha' + assert_next_tag numeric-order v2026.10.11 $'v2026.10.9-rc\nv2026.10.10-alpha\nv2026.10.2-beta' + assert_next_tag malformed-tags v2026.10.1 $'v2026.10.0\nv2026.10.01-alpha\nv2026.10.90-preview\nv2026.10.91-alpha.1\nv2026.10.92-ALPHA\nv2026.10.93-extra\nv2026.10.94.0\nv2026.010.95\nv2026x10.96\nv2026.10.-1\n2026.10.97\nv20260.10.98' } # Exercise the actual workflow block with local function stubs, without git writes or network. @@ -98,22 +98,22 @@ test_reserved_tags_are_skipped() ( gh() { case "$*" in - *refs/tags/v2026.8.0-alpha* | *refs/tags/v2026.8.1-alpha*) + *refs/tags/v2026.8.0* | *refs/tags/v2026.8.1*) printf 'gh: Reference update failed (HTTP 422)\n' >&2 return 1 ;; - *refs/tags/v2026.8.2-alpha*) return 0 ;; + *refs/tags/v2026.8.2*) return 0 ;; *) return 64 ;; esac } git() { - [ "$*" = "fetch origin refs/tags/v2026.8.2-alpha:refs/tags/v2026.8.2-alpha" ] || + [ "$*" = "fetch origin refs/tags/v2026.8.2:refs/tags/v2026.8.2" ] || fail "unexpected fetch: $*" } created=$(create_release_tag labstack/fanout deadbeef v2026.8 0) - [ "$created" = "v2026.8.2-alpha" ] || fail "created $created, want v2026.8.2-alpha" + [ "$created" = "v2026.8.2" ] || fail "created $created, want v2026.8.2" ) test_unrelated_errors_are_not_retried() ( diff --git a/site/src/content/docs/docs/get-started/install.mdx b/site/src/content/docs/docs/get-started/install.mdx index 686272ec0..27b539771 100644 --- a/site/src/content/docs/docs/get-started/install.mdx +++ b/site/src/content/docs/docs/get-started/install.mdx @@ -56,8 +56,9 @@ writable or `~/.local/bin` otherwise. Set `FANOUT_PREFIX` to choose the directory, or `FANOUT_VERSION` to pin a tag instead of taking the latest. Versions use CalVer format `vYYYY.M.N[-alpha|-beta|-rc]`, numbered from 0 within each -month across all maturity suffixes. Fanout is alpha, so -`v2026.11.0-alpha` is the first release of November 2026. GA has no suffix. +month across all maturity suffixes, so +`v2026.11.0-alpha` was the first release of November 2026. A stable release has +no suffix. Container tags omit the leading `v`, and every release moves `latest`. diff --git a/site/src/content/docs/docs/get-started/overview.mdx b/site/src/content/docs/docs/get-started/overview.mdx index 068f2121d..1be61c74a 100644 --- a/site/src/content/docs/docs/get-started/overview.mdx +++ b/site/src/content/docs/docs/get-started/overview.mdx @@ -63,5 +63,6 @@ The reference deployment target is a single small VM. ## Stability -Fanout is alpha. User-facing contracts can change without migration paths. +Stable releases follow the [upgrade policy](/docs/guides/upgrade). Capabilities +marked `preview` can still change without a migration path. The [capabilities page](/docs/reference/capabilities) lists each feature's stability. diff --git a/site/src/content/docs/docs/guides/upgrade.mdx b/site/src/content/docs/docs/guides/upgrade.mdx index 8a18b34a2..3d9727e1d 100644 --- a/site/src/content/docs/docs/guides/upgrade.mdx +++ b/site/src/content/docs/docs/guides/upgrade.mdx @@ -6,7 +6,7 @@ read_when: - You are upgrading an existing instance. - You are choosing which releases to run in production. - You maintain scripts or clients against Fanout's HTTP routes, MCP tools or settings. -status: preview +status: shipped --- ## Release channels @@ -76,10 +76,14 @@ changing a credential format; and changing the batch format. - **Prereleases** may ship a breaking change in any release, without notice. The release's upgrade notes mark it. -- **Stable releases** announce a breaking change in the notes of an earlier - stable release at least 30 days before a stable release ships it. The - announcement names what changes, its replacement, and the earliest release - that may change it. +- **Stable releases** announce a breaking change to a `shipped` capability in + the notes of an earlier stable release at least 30 days before a stable + release ships it. The announcement names what changes, its replacement, and + the earliest release that may change it. +- **`preview` capabilities** can change in any release, stable or not, without + that notice. The release's upgrade notes mark the change. The + [capabilities page](/docs/reference/capabilities) lists each capability's + status. Additions are not breaking: new routes, tools, optional fields and settings can appear in any release. @@ -91,7 +95,8 @@ changes the route registration, its clients, its authorization and the generated [HTTP routes](/docs/reference/api) and [MCP tools](/docs/reference/mcp) reference in one release, with no alias or fallback. -Deprecation is therefore a notice, not a transition period: +For `shipped` capabilities, deprecation is therefore a notice, not a transition +period: 1. A stable release's upgrade notes announce the deprecated route, field, tool or setting, with its replacement and the earliest release that removes it. diff --git a/site/src/content/docs/docs/reference/capabilities.mdx b/site/src/content/docs/docs/reference/capabilities.mdx index 591549c36..8ec0dd499 100644 --- a/site/src/content/docs/docs/reference/capabilities.mdx +++ b/site/src/content/docs/docs/reference/capabilities.mdx @@ -8,8 +8,9 @@ read_when: status: preview --- -Fanout is alpha. User-facing contracts and storage formats can change without -migration paths. Every documentation page states one of these statuses: +Stable releases follow the [upgrade policy](/docs/guides/upgrade). A `preview` +capability can still change in any release. Every documentation page states one +of these statuses: | Marker | Meaning | |---|---| From 476e59fe15932cf0745e0475a7ac4de23423e211 Mon Sep 17 00:00:00 2001 From: Vishal Rana Date: Sun, 8 Nov 2026 16:54:59 -0800 Subject: [PATCH 2/2] docs(release): remove remaining pre-release wording Align the README, capabilities page, API reference and agent map with the upgrade policy, and list SCIM and alert email as preview. --- README.md | 4 ++-- cmd/fanout-docgen/routes.go | 2 +- site/src/content.config.ts | 4 ++-- site/src/content/docs/docs/reference/api.mdx | 6 ++++-- site/src/content/docs/docs/reference/capabilities.mdx | 4 +++- site/src/pages/llms.txt.ts | 2 +- 6 files changed, 13 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 246c8182a..e94667fc6 100644 --- a/README.md +++ b/README.md @@ -15,8 +15,8 @@ Fanout's built-in agent or connect your own over MCP. Fanout keeps OpenTelemetry traces, logs, and metrics in one binary and one data directory, with no -external storage services to operate. Fanout is pre-release and changes without migration paths; the browser -client, built-in agent, MCP tools, dashboards, and alerts are preview capabilities +external storage services to operate. The browser client, built-in agent, MCP tools, dashboards, and alerts are +preview capabilities and can change without a migration path ([status](https://fanout.run/docs/reference/capabilities)). Start with the [documentation](https://fanout.run) or run it below. diff --git a/cmd/fanout-docgen/routes.go b/cmd/fanout-docgen/routes.go index 78e34448f..9e7c4637c 100644 --- a/cmd/fanout-docgen/routes.go +++ b/cmd/fanout-docgen/routes.go @@ -266,7 +266,7 @@ func renderRoutes(routes []api.RouteDoc) []byte { b.WriteString("pattern Echo matches on, not a literal URL.\n") b.WriteString("\n") - b.WriteString("## Interface stability\n\nThe `/api/*` routes serve the browser client and can change without migration\npaths. [MCP](/docs/guides/mcp) is the agent interface. OTLP ingest and\n[operational endpoints](/docs/reference/endpoints) have their own contracts.\n\nManage alert rules on the [Alerts page](/docs/guides/alerts) or through the HTTP API.\nAdministrators rotate ingest tokens on **Connect telemetry** or with\n`POST /api/settings/ingest/token/rotate`.\n\n") + b.WriteString("## Interface stability\n\nThe `/api/*` routes serve the browser client. The\n[upgrade policy](/docs/guides/upgrade) sets the notice for changes to `shipped`\ncapabilities; routes of `preview` capabilities can change without a migration\npath. [MCP](/docs/guides/mcp) is the agent interface. OTLP ingest and\n[operational endpoints](/docs/reference/endpoints) have their own contracts.\n\nManage alert rules on the [Alerts page](/docs/guides/alerts) or through the HTTP API.\nAdministrators rotate ingest tokens on **Connect telemetry** or with\n`POST /api/settings/ingest/token/rotate`.\n\n") b.WriteString("## Errors\n\nApplication API errors, including unknown routes and wrong methods, return objects shaped like\n`{\"code\":\"bad_request\",\"message\":\"Safe explanation\"}`. Codes are stable\nsnake_case identifiers; clients branch on `code` rather than message text.\nInvalid dashboard or panel specs also include `problems` with field paths,\nmessages and optional hints. Every error response uses `Cache-Control: no-store`;\nHEAD errors have no body. Server failures return a short, safe message; the\nunderlying error is logged and never returned.\n\nDefault codes by HTTP status:\n\n| Status | Code |\n|---|---|\n| 400 | `bad_request` |\n| 401 | `unauthorized` |\n| 403 | `forbidden` |\n| 404 | `not_found` |\n| 405 | `method_not_allowed` |\n| 409 | `conflict` |\n| 413 | `payload_too_large` |\n| 415 | `unsupported_media_type` |\n| 422 | `unprocessable` |\n| 429 | `rate_limited` |\n| 500 | `internal` |\n| 502 | `bad_gateway` |\n| 503 | `unavailable` |\n| 504 | `timeout` |\n\nOther 4xx statuses use `bad_request`; other 5xx statuses use `internal`.\nSpecific conditions use `already_current`, `dashboard_version_not_found`,\n`dashboard_version_conflict`, `invalid_spec` and `last_active_administrator`.\n`GET /api/telemetry/schema` returns 503 `schema_busy` with `Retry-After` when a\nnew window and namespace cannot start a discovery yet, or when the discovery is\nstill running after 15 seconds; it keeps running, so a retry finds it cached.\nCached ones are always served. An unknown window is 400 `bad_request`.\nTool failures carry `error: {code, message}` inside the tool result.\nPanel execution results keep their own status and error fields.\nOAuth, OTLP/gRPC, MCP JSON-RPC and AG-UI run errors keep their protocol spelling.\nOperational responses at `/healthz`, `/readyz` and `/metrics` keep their bodies.\n\n") diff --git a/site/src/content.config.ts b/site/src/content.config.ts index f2390c271..92605ca4c 100644 --- a/site/src/content.config.ts +++ b/site/src/content.config.ts @@ -18,8 +18,8 @@ import { docsSchema } from "@astrojs/starlight/schema"; // // shipped the binary on the current tag does this. // preview it runs, and its shape may still change without a migration. -// Fanout is pre-release and breaks things deliberately, so this -// is a real state here rather than a hedge. +// The upgrade policy exempts it from breaking-change notice, so +// this is a real state here rather than a hedge. // planned designed and written down, but nothing executes it yet. // // A page that claims more than the binary delivers is the failure these exist diff --git a/site/src/content/docs/docs/reference/api.mdx b/site/src/content/docs/docs/reference/api.mdx index ca70114ff..784e9edc0 100644 --- a/site/src/content/docs/docs/reference/api.mdx +++ b/site/src/content/docs/docs/reference/api.mdx @@ -36,8 +36,10 @@ pattern Echo matches on, not a literal URL. ## Interface stability -The `/api/*` routes serve the browser client and can change without migration -paths. [MCP](/docs/guides/mcp) is the agent interface. OTLP ingest and +The `/api/*` routes serve the browser client. The +[upgrade policy](/docs/guides/upgrade) sets the notice for changes to `shipped` +capabilities; routes of `preview` capabilities can change without a migration +path. [MCP](/docs/guides/mcp) is the agent interface. OTLP ingest and [operational endpoints](/docs/reference/endpoints) have their own contracts. Manage alert rules on the [Alerts page](/docs/guides/alerts) or through the HTTP API. diff --git a/site/src/content/docs/docs/reference/capabilities.mdx b/site/src/content/docs/docs/reference/capabilities.mdx index 8ec0dd499..a5616e714 100644 --- a/site/src/content/docs/docs/reference/capabilities.mdx +++ b/site/src/content/docs/docs/reference/capabilities.mdx @@ -41,6 +41,8 @@ capabilities uses `preview` if any of its contracts remain unsettled. | Insights and anomaly detection | preview | Detect error, latency and volume changes against rollup baselines; report insights, log patterns and a health score. | | Local email sign-in | shipped | Codes by email; no passwords. | | Local self-signup | preview | `FANOUT_SELF_SIGNUP`, off by default. Provisions viewers after code verification only. | +| SCIM user provisioning | preview | `FANOUT_SCIM_TOKEN` enables [create, update and deactivate over SCIM 2.0](/docs/concepts/authentication) in OIDC mode. | +| Alert email | preview | [Rules deliver to email addresses](/docs/guides/alerts) through the configured SMTP settings. | | OIDC account auto-provisioning | preview | Eligible identities receive the configured mapped or default role; the default is viewer. | | OIDC sign-in | shipped | Provider flow, with group and domain mapping. | | Generated settings reference | shipped | `cmd/fanout-docgen` writes it; `just check` fails when it drifts from the type. | @@ -54,6 +56,6 @@ capabilities uses `preview` if any of its contracts remain unsettled. - Namespaces filter queries. Anyone who can query an instance can query every namespace in it. Each instance is one trust domain; use separate instances for mutually untrusted teams. A namespace does not represent a user, organisation or tenant. - **No horizontal scale.** Ingest, query and maintenance share one process and one machine. - **Capacity depends on your workload.** Payload cardinality, query mix and disk determine capacity. The published benchmark measures one release, host and workload. [Measure your own hardware](/docs/concepts/performance). -- **No migration paths.** Fanout is pre-release. Storage-format changes may require a fresh data directory. Preserve backups before upgrading. +- **Preview storage has no migration path.** A batch format change may require a fresh data directory. Preserve backups before upgrading. Keep a separate copy of data you need to retain. diff --git a/site/src/pages/llms.txt.ts b/site/src/pages/llms.txt.ts index d428ebc7e..e4bd02273 100644 --- a/site/src/pages/llms.txt.ts +++ b/site/src/pages/llms.txt.ts @@ -54,7 +54,7 @@ export const GET: APIRoute = async ({ site }) => { "rules, serves a chat investigator and MCP tools, and hosts the browser client.", "", "> Use this file as a map of the Fanout documentation. Fetch any page as", - "> Markdown by appending `.md` to its URL. Fanout is pre-release: entries", + "> Markdown by appending `.md` to its URL. Entries", "> marked PREVIEW run today but may change shape without a migration path,", "> and entries marked PLANNED do not execute yet. Trust the marker over the", "> confidence of the prose.",