01
Two release refs
No exported symbol may change across two consecutive tagged release refs.
Module Stability
Know what you can rely on before you build.
Plumego separates its surface into four tiers. The 9 stable roots are the only surfaces with a long-term compatibility promise. Everything else has a label that tells you exactly how much to trust it.
This page: maturity tiers and promotion criteria. Full support matrix and router benchmarks →
9 stable roots
7 beta extensions
7 experimental extensions
v1.1.0 current version
Four tiers — each with a clear adoption signal.
Read across each row: what the tier promises, what to do with it, and which modules belong to it.
Tier API Promise Adoption signal Modules
stable Stable roots
v1 stable-root compatibility promise. Safe for production. Adopt now — these are the recommended starting point for every service. coreroutercontractmiddlewaresecuritystorehealthlogmetrics supported Supported reference
Aligned with the canonical path. Read as a guide. Use reference/standard-service as your starting template. reference/standard-servicecmd/plumego beta Beta extensions
API frozen between minor release refs. Safe to adopt with awareness — check release notes before upgrades. x/restx/gatewayx/websocketx/observabilityx/tenantx/frontendx/messaging experimental Experimental extensions
API may change. Evaluate deliberately before adopting. Adopt for clear reasons after reading the module primer and maturity evidence. x/aix/datax/fileapix/openapix/resiliencex/rpcx/validatex/data/cachex/gateway/discoveryx/gateway/ipcx/messaging/mqx/messaging/pubsubx/messaging/schedulerx/messaging/webhookx/observability/devtoolsx/observability/ops The 9 stable roots in detail.
These are the only modules with a long-term API compatibility promise. They are the recommended foundation for all production services built on Plumego.
package description status
Beta extensions — API frozen between refs.
Seven families have completed the promotion checklist: two consecutive tagged release refs with no API changes, release-backed snapshots, and owner sign-off. Safe to adopt, but check release notes before upgrading.
beta
x/rest
CRUD resource controllers and REST conventions
owner: platform-apibeta
x/gateway
Proxy, rewrite, load balancing, and edge transport
owner: edgebeta
x/websocket
WebSocket hub and explicit route registration
owner: realtimebeta
x/observability
Exporter, tracer, collector, and adapter wiring
owner: observabilitybeta
x/tenant
Per-tenant routing, quota enforcement, and JWT-backed policy
owner: tenantbeta
x/frontend
Static asset serving, SPA embedding, and pre-compressed delivery
owner: assetsbeta
x/messaging
Async messaging, queues, pubsub flows, and inbound webhook delivery
owner: messagingHow modules get promoted
A module does not become stable by declaration. Beta requires two consecutive tagged release refs with no API changes, release-backed snapshots, and owner sign-off.
02
Release-backed snapshots
API snapshots are recorded at both refs and compared automatically by CI.
03
Owner sign-off
The module owner confirms compatibility obligations in writing before the status field changes.
machine-readable ledger
Evidence tracked in specs, not prose
specs/extension-beta-evidence.yaml records release refs, snapshot paths, owner
sign-off state, and open blockers for every candidate module.
# promotion evidence for x/websocket
module: x/websocket
base_ref: v0.1.0
head_ref: v0.2.0
snapshot_base: docs/evidence/extension/snapshots/websocket-v0.1.0.json
snapshot_head: docs/evidence/extension/snapshots/websocket-v0.2.0.json
api_diff: none
owner_signoff: trueWhat runs before every release tag.
Every check below is machine-executed. A release cannot proceed if any check fails.
# one command runs all gates
make gates
# gofmt -l . ← zero unformatted files
# go run ./internal/checks/dependency-rules ← stable roots cannot import x/*
# go run ./internal/checks/module-manifests ← every module declares its boundary
# go run ./internal/checks/reference-layout ← reference apps match canonical shape
# go test -race -timeout 30s ./... ← full race-detector test suiteReady to build?
Start from the reference app, verify your module choices against the stability matrix, then expand.