Skip to content

SEMVER.md

Latest commit

 

History

History
69 lines (50 loc) · 2.63 KB

SEMVER.md

File metadata and controls

69 lines (50 loc) · 2.63 KB

Semver Policy

This document describes what constitutes a breaking change for the beamterm crate family, effective from version 1.0.0.

Library Crates

beamterm-core, beamterm-data, beamterm-rasterizer, beamterm-renderer, and beamterm-unicode follow Rust API semver conventions.

A new major version is required for any change that breaks downstream compilation or changes observable runtime behavior in ways that existing correct code would not expect.

What counts as a breaking change

  • Removing or renaming a public type, function, method, or enum variant
  • Changing function signatures (parameters, return types, trait bounds)
  • Removing a trait implementation
  • Changing the default value of a builder method
  • Bumping the MSRV (rust-version)

Third-party types in public API

The following third-party types are part of beamterm's public API surface and are re-exported from the respective crates:

Crate Re-exported from
glow beamterm-core
compact_str beamterm-core
web_sys beamterm-renderer
js_sys beamterm-renderer
wasm_bindgen beamterm-renderer

A dependency version bump (e.g. glow 0.17 → 0.18) is only a beamterm breaking change if the type signatures exposed through beamterm's API actually change. A version bump that preserves the same type signatures is a compatible (minor/patch) update.

Items excluded from semver

Items marked #[doc(hidden)] are internal implementation details shared between beamterm crates. They are not covered by semver guarantees and may change in any release.

beamterm-atlas (CLI)

beamterm-atlas is a developer tool, not a library consumed as a Rust dependency. Its stability contract is narrower:

Under semver Not under semver
CLI option names and their types Output formatting / log output
Subcommand names Default values for options
Exit code semantics (0 = success) Performance characteristics

.atlas binary format

The .atlas file format (defined in beamterm-data) is versioned and covered by semver. Specifically:

  • A new atlas format version that cannot parse older .atlas files is a breaking change and requires a major version bump.
  • New format versions must include backward-compatible deserialization so that .atlas files generated by any prior 1.x release remain loadable.