Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ Fanout's built-in agent or connect your own over MCP.
</a>

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.

Expand Down Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion cmd/fanout-docgen/routes.go
Original file line number Diff line number Diff line change
Expand Up @@ -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")

Expand Down
2 changes: 1 addition & 1 deletion docs/release.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down
2 changes: 1 addition & 1 deletion scripts/release.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
20 changes: 10 additions & 10 deletions scripts/release_test.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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() (
Expand Down
4 changes: 2 additions & 2 deletions site/src/content.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 3 additions & 2 deletions site/src/content/docs/docs/get-started/install.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

</TabItem>
Expand Down
3 changes: 2 additions & 1 deletion site/src/content/docs/docs/get-started/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
17 changes: 11 additions & 6 deletions site/src/content/docs/docs/guides/upgrade.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand Down
6 changes: 4 additions & 2 deletions site/src/content/docs/docs/reference/api.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
9 changes: 6 additions & 3 deletions site/src/content/docs/docs/reference/capabilities.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
|---|---|
Expand Down Expand Up @@ -40,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. |
Expand All @@ -53,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.
2 changes: 1 addition & 1 deletion site/src/pages/llms.txt.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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.",
Expand Down
Loading