From 0027c5b4e8c3259ff48667d68c88a0788061c91b Mon Sep 17 00:00:00 2001 From: Vishal Rana Date: Sun, 8 Nov 2026 17:35:14 -0800 Subject: [PATCH] revert: keep releases on the alpha channel Return the release script, docs and upgrade policy to alpha. Fanout is not ready to make the stable promise yet. The capabilities page keeps its SCIM and alert email rows. --- README.md | 6 +++--- cmd/fanout-docgen/routes.go | 2 +- docs/release.md | 2 +- scripts/release.sh | 2 +- scripts/release_test.sh | 20 +++++++++---------- site/src/content.config.ts | 4 ++-- .../content/docs/docs/get-started/install.mdx | 5 ++--- .../docs/docs/get-started/overview.mdx | 3 +-- site/src/content/docs/docs/guides/upgrade.mdx | 17 ++++++---------- site/src/content/docs/docs/reference/api.mdx | 6 ++---- .../docs/docs/reference/capabilities.mdx | 7 +++---- site/src/pages/llms.txt.ts | 2 +- 12 files changed, 33 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index e94667fc6..a271bb9a3 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. The browser client, built-in agent, MCP tools, dashboards, and alerts are -preview capabilities and can change without a migration path +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 ([status](https://fanout.run/docs/reference/capabilities)). Start with the [documentation](https://fanout.run) or run it below. @@ -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 (for example, `v2026.11.0-alpha`). A stable release has no suffix. +maturity suffixes. Fanout is alpha (for example, `v2026.11.0-alpha`); GA 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/cmd/fanout-docgen/routes.go b/cmd/fanout-docgen/routes.go index 9e7c4637c..78e34448f 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. 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("## 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("## 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/docs/release.md b/docs/release.md index 663d85035..f786464b6 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. For example, +release increments `N` regardless of suffix. Fanout is alpha. 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 48b4c0914..157f88388 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= +readonly PRODUCT_MATURITY=alpha die() { printf 'release: %s\n' "$1" >&2 diff --git a/scripts/release_test.sh b/scripts/release_test.sh index b87e4f932..e7fa5341b 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 $'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' + 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' } # 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* | *refs/tags/v2026.8.1*) + *refs/tags/v2026.8.0-alpha* | *refs/tags/v2026.8.1-alpha*) printf 'gh: Reference update failed (HTTP 422)\n' >&2 return 1 ;; - *refs/tags/v2026.8.2*) return 0 ;; + *refs/tags/v2026.8.2-alpha*) return 0 ;; *) return 64 ;; esac } git() { - [ "$*" = "fetch origin refs/tags/v2026.8.2:refs/tags/v2026.8.2" ] || + [ "$*" = "fetch origin refs/tags/v2026.8.2-alpha:refs/tags/v2026.8.2-alpha" ] || fail "unexpected fetch: $*" } created=$(create_release_tag labstack/fanout deadbeef v2026.8 0) - [ "$created" = "v2026.8.2" ] || fail "created $created, want v2026.8.2" + [ "$created" = "v2026.8.2-alpha" ] || fail "created $created, want v2026.8.2-alpha" ) test_unrelated_errors_are_not_retried() ( diff --git a/site/src/content.config.ts b/site/src/content.config.ts index 92605ca4c..f2390c271 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. -// The upgrade policy exempts it from breaking-change notice, so -// this is a real state here rather than a hedge. +// Fanout is pre-release and breaks things deliberately, 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/get-started/install.mdx b/site/src/content/docs/docs/get-started/install.mdx index 27b539771..686272ec0 100644 --- a/site/src/content/docs/docs/get-started/install.mdx +++ b/site/src/content/docs/docs/get-started/install.mdx @@ -56,9 +56,8 @@ 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, so -`v2026.11.0-alpha` was the first release of November 2026. A stable release has -no suffix. +month across all maturity suffixes. Fanout is alpha, so +`v2026.11.0-alpha` is the first release of November 2026. GA 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 1be61c74a..068f2121d 100644 --- a/site/src/content/docs/docs/get-started/overview.mdx +++ b/site/src/content/docs/docs/get-started/overview.mdx @@ -63,6 +63,5 @@ The reference deployment target is a single small VM. ## Stability -Stable releases follow the [upgrade policy](/docs/guides/upgrade). Capabilities -marked `preview` can still change without a migration path. +Fanout is alpha. User-facing contracts can change without migration paths. 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 3d9727e1d..8a18b34a2 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: shipped +status: preview --- ## Release channels @@ -76,14 +76,10 @@ 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 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. +- **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. Additions are not breaking: new routes, tools, optional fields and settings can appear in any release. @@ -95,8 +91,7 @@ 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. -For `shipped` capabilities, deprecation is therefore a notice, not a transition -period: +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/api.mdx b/site/src/content/docs/docs/reference/api.mdx index 784e9edc0..ca70114ff 100644 --- a/site/src/content/docs/docs/reference/api.mdx +++ b/site/src/content/docs/docs/reference/api.mdx @@ -36,10 +36,8 @@ pattern Echo matches on, not a literal URL. ## Interface stability -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 +The `/api/*` routes serve the browser client and can change without migration +paths. [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 a5616e714..46e165034 100644 --- a/site/src/content/docs/docs/reference/capabilities.mdx +++ b/site/src/content/docs/docs/reference/capabilities.mdx @@ -8,9 +8,8 @@ read_when: status: preview --- -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: +Fanout is alpha. User-facing contracts and storage formats can change without +migration paths. Every documentation page states one of these statuses: | Marker | Meaning | |---|---| @@ -56,6 +55,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). -- **Preview storage has no migration path.** A batch format change may require a fresh data directory. Preserve backups before upgrading. +- **No migration paths.** Fanout is pre-release. Storage-format changes 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 e4bd02273..d428ebc7e 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. Entries", + "> Markdown by appending `.md` to its URL. Fanout is pre-release: 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.",