Versioning & Releases

telectl follows Semantic Versioning 2.0 with Kubernetes-style pre-release stages.

Version Scheme

v<major>.<minor>.<patch>[-<prerelease>]

flowchart LR
    A["v0.1.0-alpha.1"] --> B["v0.1.0-alpha.2"]
    B --> C["v0.1.0-beta.0"]
    C --> D["v0.1.0-rc.1"]
    D --> E["v0.1.0"]
    E --> F["v0.1.1 (patch)"]
    E --> G["v0.2.0 (minor)"]

Golden Rules

1. Tags are immutable. A broken release is fixed by the next version (v0.1.0-alpha.1 broken → ship v0.1.0-alpha.2), never by deleting and re-pushing the same tag. Reusing a tag means anyone who already pulled it gets a different artifact than the tag claims — breaking reproducibility.
2. Bump rules (SemVer):
   • major — breaking API changes
   • minor — new features, backwards compatible
   • patch — backwards-compatible fixes
   • prerelease — incremented per pre-release (.1, .2, …)
3. One release per tag push. CI builds binaries, checksums, and the multi-arch GHCR image, then creates the GitHub Release.

How a Release Happens (CI)

flowchart TB
    T[push tag v0.1.0-beta.0] --> C{CI workflow}
    C --> Tidy[Go Mod Tidy]
    C --> Test[Test + vet + gofmt]
    C --> Lint[golangci-lint]
    Tidy --> B[Build]
    Test --> B
    Lint --> B
    B --> REL[Create Release]
    B --> D[Docker Image amd64+arm64]
    D --> GHCR[(GHCR)]
    REL --> GH[(GitHub Release + binaries + checksums)]

Current Releases

Changelog

See CHANGELOG.md in the repository (Keep a Changelog format).

Next: Architecture Overview · Security