API Stability Policy¶
GTB uses a three-tier stability classification to set clear expectations for consumers and contributors. Each public type, interface, and function belongs to one of the tiers below.
Stable API
As of v1.11.0, GTB honours full API stability. Breaking changes to Stable and Beta tier APIs require a major version bump (v2.0.0+). The v1.10.x to v1.11.0 transition includes a breaking change to pkg/config constructor signatures (options pattern migration). The guarantee takes full effect from v1.11.0 onwards.
Stability Tiers¶
Stable¶
APIs in this tier are intended for long-term use. Breaking changes require a major version bump.
Deprecations require at least one minor-version notice before removal in the next major version.
| Package | Type / Interface / Function | Since |
|---|---|---|
pkg/props |
Props struct (public fields) |
v0.1 |
pkg/props |
LoggerProvider, ConfigProvider, ErrorHandlerProvider |
v0.1 |
pkg/props |
Tool, Version, Assets types |
v0.1 |
pkg/props |
SetFeatures, Enable, Disable, feature constants |
v0.1 |
pkg/config |
Containable interface |
v0.1 |
pkg/config |
Container (all public methods) |
v0.1 |
pkg/config |
NewFilesContainer, NewReaderContainer, LoadFilesContainer |
v0.1 |
pkg/logger |
Logger interface |
v1.0 |
pkg/logger |
Level, Formatter types and constants |
v1.0 |
pkg/logger |
NewCharm, NewNoop |
v1.0 |
pkg/controls |
Controllable, Runner, StateAccessor, Configurable, ChannelProvider interfaces |
v0.1 |
pkg/controls |
StartFunc, StopFunc, StatusFunc types |
v0.1 |
pkg/controls |
ServiceOption, WithStart, WithStop, WithStatus |
v0.1 |
pkg/controls |
NewController, WithLogger, WithoutSignals |
v0.1 |
pkg/controls |
State, Message, HealthMessage, HealthReport types |
v0.1 |
pkg/errorhandling |
ErrorHandler interface |
v0.1 |
pkg/errorhandling |
New, WithHint, WithHintf, WrapWithHint |
v0.1 |
pkg/setup |
Register* functions |
v0.1 |
pkg/credentials |
Mode type, ModeEnvVar/ModeKeychain/ModeLiteral constants, ErrCredentialNotFound/ErrCredentialUnsupported sentinels |
v1.11 |
pkg/credentials |
Backend interface, RegisterBackend, KeychainAvailable, AvailableModes, Probe |
v1.12 |
pkg/credentials |
Store/Retrieve/Delete package-level helpers |
v1.12 |
pkg/credentials/keychain |
Backend struct (go-keyring implementation) |
v1.12 |
pkg/credentials/credtest |
MemoryBackend, Install |
v1.12 |
pkg/vcs |
ResolveToken, ResolveTokenContext |
v1.11 (ResolveToken), v1.12 (ResolveTokenContext) |
Beta¶
These APIs are functionally complete but may have minor breaking changes in minor versions. Changes will be documented in migration guides.
| Package | Type / Interface / Function | Since |
|---|---|---|
pkg/chat |
ChatClient interface and all methods |
v0.x |
pkg/chat |
New, ProviderClaude, ProviderOpenAI, ProviderGemini |
v0.x |
pkg/cmd/doctor |
Doctor check registration API | v0.x |
pkg/http |
Start, Stop, NewSecureClient |
v0.x |
pkg/grpc |
New, Start, Stop |
v0.x |
pkg/controls |
WithLiveness, WithReadiness, WithRestartPolicy, RestartPolicy |
v0.x |
pkg/vcs/github |
NewClient, ReleaseProvider interface |
v0.x |
pkg/vcs/gitlab |
NewClient, ReleaseProvider interface |
v0.x |
pkg/vcs/repo |
Repo struct and all public methods |
v0.x |
pkg/setup |
NewUpdater(ctx, props, version, force) |
v1.12 (signature updated from v1.11's context-free form) |
Experimental¶
These APIs may change significantly or be removed without notice. Do not depend on them in production code without pinning to a specific version.
| Package | Scope | Note |
|---|---|---|
internal/* |
All packages | Always unstable — import not supported |
pkg/forms |
All types and functions | Subject to charmbracelet/huh API changes |
pkg/setup/ai, pkg/setup/github |
All types and functions | Configuration UX still evolving |
Semver Commitments¶
| Version range | Policy |
|---|---|
v1.0.0 to v1.9.x |
Historical — Unstable: Breaking changes occurred in minor versions during the rapid development phase. |
v1.10.0 to v1.10.x |
Transitional: The pkg/config constructor signatures were migrated to an options pattern, which is a breaking change included in v1.11.0. |
v1.11.0+ |
Guaranteed Stability: Standard Go semver. Breaking changes require a major version bump (v2.0.0+). |
v1.12.0 |
pkg/credentials.Backend gained context.Context on every method. pkg/setup.NewUpdater signature changed to accept ctx as first parameter. Both were introduced in v1.11.0 and refined in v1.12.0 before external uptake; see migration guide. |
The internal/ directory is always unstable regardless of version — it is not
part of the public API surface.
Deprecation Policy¶
- A deprecated API is annotated with a
// Deprecated:Go doc comment describing what to use instead. - The deprecation is documented in the next minor-version migration guide.
- The API is removed no earlier than the following major version.
- For pre-v1.0 releases, deprecated APIs may be removed in the next minor version (with a migration guide entry).
Checking for Breaking Changes¶
Use apidiff to detect API-level breaking changes between versions:
go install golang.org/x/exp/cmd/apidiff@latest
apidiff -m gitlab.com/phpboyscout/go-tool-base v0.9.0 v1.0.0
Breaking changes to Stable-tier APIs detected by apidiff must not be merged
without a major version bump.