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.

Pre-1.0 — tiers describe intent, not a current guarantee

GTB is currently pre-1.0 (v0.x). While the module is v0.x the public API is not frozen: breaking changes are permitted and ship as a minor version bump (v0.N → v0.N+1). The version annotations and tier guarantees in the tables below describe the stability commitment that takes effect from v1.0 — they are not in force yet. Use them to understand which APIs are intended to be stable, and expect that any of them may still change before v1.0. The just apidiff target and the advisory (non-blocking) CI apidiff job exist to make pre-1.0 API changes visible so they are seen and intentional; that gate becomes blocking at v1.0.

The Since columns below record when each symbol first appeared in its current shape; some annotations (e.g. v1.11, v1.12) predate the move to v0.x versioning and should be read as relative ordering, not literal released tags.

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
`go/config` (module)	`Store`, `View`, `Reader`, `Binder` and the layered-source constructors	versioned by the standalone `gitlab.com/phpboyscout/go/config` module, not by GTB
`pkg/logger`	`Logger` interface	v1.0
`pkg/logger`	`Level`, `Formatter` types and constants	v1.0
`pkg/logger`	`NewCharm`, `NewNoop`	v1.0
`pkg/setup`	`Register*` functions	v0.1
`pkg/vcs`	`ConfigFromReader` (config→`forge.Config` bridge; token resolution moved to `go/forge`)	v0.x

Extracted modules are not covered by this policy

Several packages that once lived in pkg/ are now standalone modules with their own release cadence, so GTB cannot make stability promises about them — their API is versioned by the module, not by this framework.

Module	Docs
`gitlab.com/phpboyscout/go/controls`	controls.go.phpboyscout.uk
`gitlab.com/phpboyscout/go/credentials` (+ `/keychain`, `/credtest`)	credentials.go.phpboyscout.uk
`gitlab.com/phpboyscout/go/errorhandling`	errorhandling.go.phpboyscout.uk

What GTB does commit to is the thin adapter layer it keeps around each of them — the *FromProps / *FromContainable settings constructors listed above — since those are GTB's own API.

For the full list of what moved and when, see the migration guides.

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/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/setup/ai`, `pkg/setup/forge`	All types and functions	Configuration UX still evolving

Semver Commitments¶

Version range	Policy
`v0.x` (current)	Unstable — pre-1.0: Breaking changes to any public API are permitted and ship as a minor bump. The tier tables above describe the intended v1.0 commitment, not a current guarantee. Prefer backward-compatible changes where cheap; document any break in `docs/reference/migration/`.
`v1.0.0+`	Guaranteed Stability (future): From the first `v1.0.0` release, standard Go semver applies — breaking changes to Stable and Beta tier APIs require a major version bump (v2.0.0+), and the advisory CI `apidiff` job becomes a blocking gate.

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:

just apidiff   # compares the working tree against the latest release tag

just apidiff installs golang.org/x/exp/cmd/apidiff on demand and runs apidiff -m gitlab.com/phpboyscout/go-tool-base <latest-tag> .. The CI apidiff job runs the same comparison on every merge request.

Pre-1.0: the comparison is advisory — incompatible changes are expected (they ship as minor bumps) and the CI job is non-blocking (allow_failure: true). Its purpose is visibility: an API change should be seen and intentional, reflected in the diff a reviewer reads.

From v1.0: breaking changes to Stable- and Beta-tier APIs detected by apidiff must not be merged without a major version bump, and the CI job becomes blocking.