API compatibility policy¶
This document describes the v1.x compatibility contract for recourse.
SemVer policy¶
- The root module follows SemVer.
- For v1.x, exported APIs in the stable packages listed below will not change in a breaking way.
- Additive changes are allowed. Removals or breaking changes require a v2 release.
- Deprecations will be documented in release notes and code comments.
Stable packages (root module)¶
These packages are part of the v1.x stability contract:
github.com/aponysus/recourse/recoursegithub.com/aponysus/recourse/retrygithub.com/aponysus/recourse/policygithub.com/aponysus/recourse/observegithub.com/aponysus/recourse/classifygithub.com/aponysus/recourse/budgetgithub.com/aponysus/recourse/controlplanegithub.com/aponysus/recourse/circuitgithub.com/aponysus/recourse/hedgegithub.com/aponysus/recourse/integrations/http
Separate modules: gRPC and OpenTelemetry integrations¶
The gRPC and OpenTelemetry integrations are separate modules:
github.com/aponysus/recourse/integrations/grpcgithub.com/aponysus/recourse/integrations/otel
They follow SemVer in their own modules. The intent is to version them in lockstep with the root module, but they are independently tagged.
Not part of the API contract¶
internal/packagesexamples/packages- Test-only helpers
Telemetry contract¶
The following are considered stable for v1.x:
observe.Timeline,observe.AttemptRecord, andobserve.BudgetDecisionEventfieldsOutcome.Reasonvalues and budget/circuit reason codes
See the generated references:
Go version support¶
The root module's supported Go version is defined by the repository root go.mod (currently 1.23).
Optional integration modules define their own minimum Go versions in their nested go.mod files because their dependency graphs are intentionally isolated from the root module:
integrations/grpc: currently Go 1.24.integrations/otel: currently Go 1.25.
Example modules are not part of the API contract and may use the Go version required by the integration they demonstrate.