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
--targetvalues
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:
Language surface: Code that compiled successfully before now fails to compile or produces different runtime behavior
Stdlib API: Function signatures change or functions are removed
CLI contract: Command options change or exit codes change
Target model: Existing
--targetvalues become invalidDiagnostics: Error codes change meaning or are removed
Deprecation process
Before making a breaking change:
Document the deprecation in the relevant stdlib module documentation
Add a deprecation warning in the compiler or runtime (where feasible)
Maintain the old API for at least one MINOR version
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 functionsStable diagnostics: Error code contracts and runtime error model
Stable target model:
--targetvalues and host matrix
Changes to items in the stable API require:
Documentation update in
stable-api.rstIncrement of MAJOR version if breaking
Increment of MINOR version if additive
Update of
VERSIONfileRelease 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.rstThey 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 --versioncommandkarkain versionCLI commandGenerated 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
VERSIONfile is the single source of truth for version numbersAll other version references must be kept in sync
CI builds should verify version consistency
Release tags must match the
VERSIONfile 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