Skip to content

VERSIONING.md

Latest commit

 

History

History
106 lines (83 loc) · 5.1 KB

VERSIONING.md

File metadata and controls

106 lines (83 loc) · 5.1 KB
Raw

Versioning Policy

This project follows Semantic Versioning 2.0.0 with compiler-specific interpretations.

Format: MAJOR.MINOR.PATCH

Pre-1.0 (current)

While below 1.0, the language spec is unstable. Minor versions may include breaking changes to syntax or semantics. The rules below describe intent, not hard guarantees.

MAJOR (X.0.0)

Bump when the language makes a backward-incompatible change to stabilized features. Programs that compiled under the previous major version may require source changes.

Examples:

  • Removing or renaming a keyword
  • Changing the semantics of an existing operator
  • Removing a stdlib function that was marked stable
  • Changing the default calling convention or ABI

The bump from 0.x to 1.0 means: the core language spec is frozen. Existing programs will not break without a deprecation cycle.

MINOR (0.X.0)

Bump when new functionality is added in a backward-compatible way. Existing programs continue to compile and behave identically.

Examples:

  • New keyword or syntax (e.g., comptime, where clauses)
  • New stdlib module or function
  • New CLI subcommand (e.g., seen fmt, seen lsp)
  • New compiler flag (e.g., --null-safety, --emit-glsl)
  • New target platform or cross-compilation support
  • New language keyword translations (adding a 7th language)

PATCH (0.0.X)

Bump when existing functionality is fixed or improved without changing the public interface. Existing programs compile and behave the same or better.

Examples:

  • Codegen bug fix (wrong IR, type mismatch, linker error)
  • Optimizer fix (loop miscompilation, incorrect flag propagation)
  • Runtime bug fix (HashMap, Array, StringBuilder)
  • Performance improvement (faster compilation, smaller binaries)
  • Build system fix (path resolution, caching, stale artifacts)
  • Compiler crash fix
  • Error message improvement

What doesn't require a version bump

  • Internal refactoring (splitting codegen modules, renaming internal variables)
  • Documentation changes
  • Test additions
  • CI/CD changes
  • Development tooling (VSCode extension versioned separately)

Release process

  1. Update CHANGELOG.md with the new version entry.
  2. Construct CompatibilityReleaseInputs with every compiler, runtime, standard-library, package-client, LLVM, ABI, platform, and target identity; generate releases/compatibility-manifest.json with the native Seen writeCompatibilityManifest API. The generator never supplies defaults.
  3. Validate the generated bytes with python3 scripts/check_compatibility_manifest.py releases/compatibility-manifest.json.
  4. Tag the commit: git tag v0.X.Y.
  5. Run ./scripts/safe_rebuild.sh to verify bootstrap.
  6. Run bash tests/e2e_multilang/run_all_e2e.sh to verify 66/66 tests pass.

Compatibility manifest

releases/compatibility-manifest.json is the machine-readable release compatibility contract. Its strict JSON shape is versioned by schemas/compatibility-manifest.schema.json; unknown fields, unordered or duplicate targets, unsupported targets, mismatched compiler/package-client versions, and inputs above the byte limit fail closed. Linux x86-64 is the required Gate 0 target. Linux ARM64, macOS, and Windows remain declared as toolchain-dependent rather than being presented as locally verified.

The native model, bounded validation, strict decoder, deterministic renderer, and atomic output API live in compiler_seen/src/release/compatibility.seen. generateCompatibilityManifest requires every compatibility value explicitly, and consumeCompatibilityManifest compares canonical bytes against the complete runtime expectation. The compiler performs that check before launching its version-coupled package client. Source checkouts consume the canonical record under releases/; installers ship the same bytes beside seen. Missing, unknown, unordered, duplicated, unsupported, or mismatched values fail closed with core.002b.* diagnostics and are never repaired.

The compatibility manifest's components.compiler.package_interface_schema entry binds reusable source-package compatibility. Its seen-package-interface-v2 value includes the independently versioned native seen-package-layout-v1 contract. Reusable packages expose src/mod.seen as their explicit library entry and retain root Seen.toml, Seen.lock, tests/, examples/, README.md, and LICENSE paths. A different or incomplete layout is a breaking alpha contract change and must update the manifest binding, native validator, fixtures, and consumers together.

The schema validator's pinned microbenchmark uses five warmups and thirty samples with a hard five-percent regression ceiling: python3 scripts/benchmark_compatibility_manifest.py releases/compatibility-manifest.json tests/fixtures/core-002a/happy/benchmark.json. The runtime generate/consume benchmark uses the same sample policy and applies the hard five-percent ceiling to its ratio against a same-process canonical JSON control workload, so the pinned gate remains meaningful across runner speeds: python3 scripts/benchmark_compatibility_runtime.py releases/compatibility-manifest.json tests/fixtures/core-002b/happy/benchmark.json.