API and Go Client Stability

This policy covers the public REST API under /api/v1, represented by pkg/apiserver/docs/swagger.yaml, and the exported Go API in pkg/client. Internal packages, alpha or experimental features explicitly documented as such, and the OpAMP protocol endpoint are outside this policy.

The REST API and Go client are versioned together with OpAMP Commander; the client does not have an independent version.

Compatibility promise

OpAMP Commander follows Semantic Versioning:

• Patch releases preserve backward compatibility.
• Before v1.0.0, a minor release may contain a previously announced breaking change. After v1.0.0, breaking changes require a major release.
• Adding an optional endpoint, field, parameter, or exported Go symbol is backward-compatible. Removing or renaming one, changing its type or meaning, or making an optional input required is breaking.

The OpenAPI CI check blocks pull requests that remove or incompatibly change the committed REST contract. An intentional breaking change requires a documented migration and an explicit maintainer override. Go client compatibility is reviewed as part of changes to exported pkg/client symbols.

Deprecation process

Before removing or incompatibly changing a public API:

1. Mark it deprecated in Swagger and, for Go, with a Deprecated: doc comment.
2. Document the replacement and migration path in the same change.
3. Include the deprecation in the GitHub release notes generated by GoReleaser.
4. Keep it available for at least one minor release. After v1.0.0, keep it for at least 90 days as well.
5. Remove it only in a release allowed to break compatibility under the policy above.

An urgent security or data-integrity fix may shorten this window. Its release notes must explain the exception and migration path.

Release notes are generated from conventional commit subjects and grouped into breaking changes, features, bug fixes, and other changes. Use ! before the colon for a breaking change, for example feat(api)!: remove legacy selector.