ka2a documentation

Versioning

Developer preview. Not yet production ready. This page is rendered from docs/versioning.md of the ka2a repository at revision 96fb45e5e5f6693e779837998c3aa9581d6a37f2. It describes the behavior of that revision.

Contents

This policy applies from the first release of the R2 code. No release of the R2 code exists yet. The tag v0.1.0-alpha.1 in the repository names a commit of the pre-R2 tree (branch archive/pre-r2-reset), not this code. The changelog records the changes.

Version numbers

ka2a uses Semantic Versioning 2.0.0 with a v prefix: vMAJOR.MINOR.PATCH, with an optional pre-release suffix such as -alpha.1 or -rc.1. make release-artifacts refuses another form.
One version covers the Go module github.com/k-a2a/ka2a, the ka2a command and the release artifacts. ka2a version prints the version and the commit of a release build.
While the major version is 0 (the developer preview), a MINOR release can contain breaking changes. A PATCH release contains only fixes and no intended breaking change of the stable surface below.
From v1.0.0, a breaking change of the stable surface needs a new major version. The module path then gets the suffix /v2, as Go requires.

The stable surface of the preview

These parts follow the rules above. The changelog names each breaking change in a MINOR release with a migration note.

Surface	Rule
Go packages `pkg/ka2a`, `pkg/protocol` and `pkg/observe`	Exported names, signatures and documented behavior.
Error codes (`ka2a.Code`) and their meaning	A code is not renamed or reused for another meaning. New codes can be added; handle unknown codes as failures. The error reference lists them.
The `ka2a` command line	Command names, flags, exit codes 0 to 6.
Versioned JSON outputs (the member `format`, for example `ka2a.doctor/1`)	The compatibility rule of Output formats: a version only gains members; a removed, renamed or retyped member, or a changed meaning, makes a new version. A test enforces it.
The wire profile `KA2A-WIRE-1`	Frozen. A change needs a new profile name and a paired review (see `wire-profile.md` of the change).
The catalog format `ka2a.catalog.v1` and the key file `ka2a.signing-key.v1`	A new version of the format gets a new name.
The store schema (`store_schema` in `ka2a version`)	A newer binary migrates an older store at the owner open. An older binary refuses a newer store (`schema_too_new`). See Upgrade notes.
Snapshot files (`ka2a.snapshot/N`)	Same rule as the JSON outputs. A reader reads a snapshot strictly and refuses unknown members, so read a snapshot with the ka2a revision that wrote it or a newer one (see Output formats).

What is not stable

Re-exported types of A2A: the public API of pkg/ka2a uses the types of github.com/a2aproject/a2a-go/v2/a2a (pinned to v2.6.0), for example a2a.Task and a2a.SendMessageRequest. When ka2a moves to a newer a2a-go version, these types change as a2a-go changes them. The changelog names the a2a-go version of each release. ka2a does not wrap them.
Packages under internal/. Go does not let other modules import them.
Human-readable text output, log lines and their order. Parse --output json instead.
The operational UI pages.
Metric names and labels in the preview (see the metrics reference). A rename is named in the changelog.
Default limits, timeouts and retention periods. A change of a default is named in the changelog.
Test helpers, scripts, reports and the files under verification/.

Deprecation policy

A deprecated Go identifier gets a Deprecated: paragraph in its doc comment. It names the replacement.
A deprecated flag or command still works. ka2a help names it as deprecated.
The changelog lists each deprecation under "Deprecated".
In the preview, a deprecated item stays for at least one MINOR release before its removal. From v1.0.0, it stays until the next major version.
A security fix can remove or change behavior without a deprecation period. The changelog and the advisory say so.

Supported Go versions

The go directive of go.mod is the floor: Go 1.27.0. The CI and all qualification runs use Go 1.27.0 (.go-version). No other Go version was tested.
Build with CGO_ENABLED=0. A build with cgo is not a supported build.
ka2a intends to support the two newest major Go releases, as the Go project does. A release that raises the floor is a MINOR release, and the changelog names the new floor.
The release binaries record their Go version (ka2a version).

Supported platforms

The table "Supported platforms" of the README is the list. It says which platforms had tests.

Compatibility between endpoints

Endpoints exchange records with KA2A-WIRE-1. Endpoints with different ka2a versions work together while both use the same wire profile and the same catalog format. Upgrade one endpoint at a time and follow the Upgrade notes when the store schema changes.

All ka2a documents