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.",