Semantic Versioning Policy (SemVer)

Karkain follows Semantic Versioning 2.0.0 (SemVer) for versioning the language, toolchain, and standard library. This policy defines how version numbers are assigned and what constitutes a breaking change.

Version format

Karkain uses the standard SemVer format: MAJOR.MINOR.PATCH

  • MAJOR: Incompatible API changes

  • MINOR: Backwards-compatible functionality additions

  • PATCH: Backwards-compatible bug fixes

Additional labels:

  • -beta.N: Pre-release beta versions (e.g., 1.0.0-beta.1)

  • -rc.N: Release candidate versions (e.g., 1.0.0-rc.1)

  • +build: Build metadata (e.g., 1.0.0+20260914)

Current version

Current stable version: 1.0.0 (since Phase 119)

The stable version is defined in the VERSION file at the repository root and reflected across: * Go CLI banner * kcc binary banner * Generated C header comments * Documentation version markers

When to increment

MAJOR (X.0.0 → Y.0.0)

Increment the MAJOR version when:

  • Removing or renaming stable language syntax

  • Removing or changing the signature of stable stdlib functions

  • Changing the behavior of a stable stdlib function in an incompatible way

  • Removing stable CLI commands or changing their exit codes

  • Changes to the stable diagnostic error codes (K001–K113)

  • Changes to the target model that break existing --target values

MINOR (1.0.0 → 1.1.0)

Increment the MINOR version when:

  • Adding new stable language syntax

  • Adding new stable stdlib modules or functions

  • Adding new stable CLI commands

  • Adding new target architectures

  • Adding new features that don’t break existing code

PATCH (1.0.0 → 1.0.1)

Increment the PATCH version when:

  • Bug fixes that don’t change stable APIs

  • Performance improvements

  • Documentation updates

  • Tooling improvements (build, install, CI)

Breaking change policy

What constitutes a breaking change

A change is considered breaking if:

  1. Language surface: Code that compiled successfully before now fails to compile or produces different runtime behavior

  2. Stdlib API: Function signatures change or functions are removed

  3. CLI contract: Command options change or exit codes change

  4. Target model: Existing --target values become invalid

  5. Diagnostics: Error codes change meaning or are removed

Deprecation process

Before making a breaking change:

  1. Document the deprecation in the relevant stdlib module documentation

  2. Add a deprecation warning in the compiler or runtime (where feasible)

  3. Maintain the old API for at least one MINOR version

  4. Remove the deprecated API in the next MAJOR version

Stable API definition

The stable API is defined in docs/source/reference/stable-api.rst and includes:

  • Stable syntax: Language constructs that are guaranteed to work

  • Stable CLI: Commands, options, and exit codes

  • Stable stdlib: Importable std.* modules and their functions

  • Stable diagnostics: Error code contracts and runtime error model

  • Stable target model: --target values and host matrix

Changes to items in the stable API require:

  • Documentation update in stable-api.rst

  • Increment of MAJOR version if breaking

  • Increment of MINOR version if additive

  • Update of VERSION file

  • Release notes describing the change

Experimental vs Stable

Items marked as Experimental in docs/source/status/scope.rst are not part of the stable API and may change without MAJOR version increments.

Experimental items become stable when:

  • They have been tested in beta releases

  • They have documentation in stable-api.rst

  • They pass the relevant phase gates

  • The maintainer explicitly promotes them to stable

Feature freeze during releases

During release candidate preparation (RC phase), the project operates under a feature freeze:

  • No new major language features

  • No unnecessary syntax changes

  • No broad stdlib redesign

  • No compiler architecture rewrite

See Feature-Freeze Policy (Beta / Release-Candidate) for details on what is allowed during freeze.

Version verification

The version is verified by:

  • karkain --version command

  • karkain version CLI command

  • Generated C header comments

  • Phase 118 RC gate test

  • Release checklist verification

Cross-engine parity

Karkain maintains byte-identical behavior between the Go engine and the self-hosted kcc engine for all stable APIs. Changes that break this parity require:

  • Both engine implementation updates

  • Parity gate tests passing

  • Documentation of the parity restoration

Implementation notes

  • The VERSION file is the single source of truth for version numbers

  • All other version references must be kept in sync

  • CI builds should verify version consistency

  • Release tags must match the VERSION file at the time of tagging

See also

Feature-Freeze Policy (Beta / Release-Candidate) — Release-candidate feature freeze policy Compatibility Policy — Compatibility guarantees Stable API Snapshot (1.2.0) — Current stable API snapshot