Stability & versioning

Current state

• Version: see build.zig.zon in the repo.
• Stability: pre-1.0. Internal-stable, externally moving.
• Breaking changes: tracked in CHANGELOG.md per release.

Versioning policy

Pre-1.0

• MAJOR.MINOR.PATCH semantics with looser MINOR guarantees.
• Minor bumps may introduce breaking API changes.
• Patch bumps are non-breaking.

Post-1.0 (target Q4 2026 — one full quarter of revisions without a breaking change)

• Strict semver. Minor bumps add only; major bumps may break.
• LTS minor versions get 6 months of patch-only support.

How to pin

Pin to a commit hash in build.zig.zon:

.tomoul = .{
    .url  = "https://github.com/tomoul/tomoul/archive/<commit>.tar.gz",
    .hash = "...",
},

Upgrade deliberately. Read the changelog before bumping.

Deprecation cadence

When we plan to remove something pre-1.0:

1. Marked deprecated in the release that introduces the replacement.
2. Removed no sooner than the next minor release.
3. Removal is called out at the top of CHANGELOG.md.

Road to 1.0

Gates we want to clear:

• One full quarter (~3 months) of releases with no breaking changes.
• The six architecture families stabilised against external consumers' real workloads.
• C ABI stable.
• A documented module-surface contract: which symbols are public, which are internal.

Track the 1.0 milestone →