Skip to content
PLUMEGO stdlib-shaped Go services with explicit wiring.
EN

Extension Stability Policy

Extension Stability Policy

Section titled “Extension Stability Policy”

This document defines the criteria for advancing an x/* extension module from experimental to beta (stable-candidate), and from beta to ga.

It does not override the stable-root compatibility promise defined in Deprecation Policy. Stable roots follow a separate, stronger policy.

Status ladder

Section titled “Status ladder”

The status field in each module’s module.yaml tracks position on this ladder:

StatusMeaning
experimentalAPI shape may change; no compatibility expectation
betaAPI shape is stable within the current major version; breaking changes require deprecation notice
gaFull v1 compatibility promise; follows Deprecation Policy

All x/* modules start as experimental. Promotion is explicit and requires meeting the criteria below.

Promotion evidence is tracked in specs/extension-beta-evidence.yaml. A module remains experimental until both the evidence file and the module manifest are updated in a promotion card.

Criteria for experimental → beta

Section titled “Criteria for experimental → beta”

An extension may be proposed as beta when all of the following are true:

  1. Stable public API surface. No exported symbol changes have been needed for at least two consecutive minor releases. All public types use constructor injection rather than mutable fields or global registration.

  2. Boundary compliance. The module passes go run ./internal/checks/dependency-rules with no violations. It does not import stable roots in ways that would force stable-root changes to accommodate it.

  3. Test coverage. The module has unit tests for every documented public behavior path, including negative paths (errors, empty inputs, context cancellation). The test suite runs cleanly with go test -race ./....

  4. Module manifest. The module.yaml is complete and schema-valid (go run ./internal/checks/module-manifests). responsibilities, non_goals, review_checklist, and agent_hints accurately describe the current implementation.

  5. Module primer. The primer under docs/modules/ documents all public entrypoints, boundary rules, and a validation command. It is consistent with the current API surface (not aspirational).

  6. No known regressions. No open regression reports against the module’s documented behavior.

  7. Owner sign-off. The module owner listed in module.yaml confirms the criteria are met.

Criteria for beta → ga

Section titled “Criteria for beta → ga”

In addition to maintaining all beta criteria, a beta module must:

  1. Production usage evidence. At least one production deployment (internal or external) is documented or known to the owner.

  2. Two-release stability. The beta status has been held for at least two consecutive minor releases with no breaking changes.

  3. Deprecation pathway. Any symbols previously deprecated while in experimental or beta have been removed or have a documented removal timeline.

  4. GA compatibility claim reviewed. The module owner and a stable-root reviewer have confirmed the public surface is ready for the full Deprecation Policy promise.

Promotion process

Section titled “Promotion process”
  1. Open a task card in tasks/cards/active/ referencing this policy.
  2. Update specs/extension-beta-evidence.yaml with required release refs, exported API snapshot refs, blocker state, and owner sign-off.
  3. Generate or compare exported API snapshots with go run ./internal/checks/extension-api-snapshot.
  4. For release-to-release evidence, compare selected refs with go run ./internal/checks/extension-release-evidence.
  5. Validate the evidence ledger and blocker state with go run ./internal/checks/extension-beta-evidence.
  6. Update the status field in the module’s module.yaml.
  7. Update the module’s primer under docs/modules/ to reflect the new status.
  8. Update docs/release/roadmap.md to record the promotion.
  9. The CI-equivalent release gate must pass before merging: make gates.

Current evaluation

Section titled “Current evaluation”
ModuleCandidate forStatus / remaining action
x/restbetaBlocked until release-history evidence proves two consecutive minor releases without exported API changes
x/websocketbetaBlocked until release-history evidence proves two consecutive minor releases without exported API changes
x/tenantbetaBlocked until release-history evidence proves two consecutive minor releases without exported API changes
x/observabilitybetaBlocked until release-history evidence proves two consecutive minor releases without exported API changes
x/gatewaybetaBlocked until release-history evidence proves two consecutive minor releases without exported API changes

Not yet evaluated or with clear open work: x/ai (stable-tier subpackages evaluated individually), x/gateway/discovery, x/data, x/messaging/scheduler, x/messaging/webhook, x/messaging, x/messaging/mq, x/messaging/pubsub.

Non-goals

Section titled “Non-goals”
  • Do not promote x/* packages to ga without this process.
  • Do not weaken the stable-root promise to accommodate extension promotion.
  • Do not let beta status become a permanent holding pattern; set a target release for ga at promotion time or record the blocker explicitly.
Section titled “Read next”