Tagging Strategy¶

APX uses subdirectory-scoped git tags to version individual API lines independently within a single canonical repository.

Tag Format¶

Tags follow the pattern:

<api-id>/v<semver>

Examples:

API Line vs Release Version¶

These are different concepts:

• API line (v1, v2) = compatibility namespace. Only changes on breaking changes.
• Release version (v1.0.0-beta.1, v1.1.0) = SemVer release of that line.

What stays stable¶

The import path does not change between pre-release and GA:

// This import is the same whether you're on alpha, beta, or GA
import ledgerv1 "github.com/acme/apis/proto/payments/ledger/v1"

Only the resolved module version changes:

# During beta
go get github.com/acme/apis/proto/payments/ledger@v1.0.0-beta.1

# At GA
go get github.com/acme/apis/proto/payments/ledger@v1.0.0

What triggers a new API line¶

Only breaking changes create a new API line (v1 → v2). This means a new directory, new import path, and consumers must explicitly opt in:

import ledgerv2 "github.com/acme/apis/proto/payments/ledger/v2"

Lifecycle Metadata¶

Lifecycle state is tracked separately from the version tag:

Inspect Tags¶

Use apx inspect to see what tags would be created:

apx inspect release proto/payments/ledger/v1@v1.0.0-beta.1