craft-libs/docs/versioning.md

# Versioning and releases

craft-libs releases give applications a fixed dependency baseline. Consumers decide when to
upgrade; development on `main` is not a reason to refresh a working application's pins.

## One workspace, one release

All crates inherit `workspace.package.version` and ship together under an annotated `vX.Y.Z`
Git tag. A release contains the crates listed in that tag's README, not proposed crates in
open pull requests. A crate can keep the same implementation across several workspace releases.
Use the same tag or commit for every craft-libs dependency in a consumer's dependency graph;
mixing Git sources can create duplicate crate instances and incompatible Rust types.

Tags identify reviewed commits and are never moved, deleted or reused to fix a release.
Corrections get a new version. The release notes and policy are stored with the source so a
consumer can read the contract that applied to its version. GitHub Releases carry the same notes.
Publishing to crates.io will be a separate step; these tags do not imply registry availability.

## Compatibility while versions are 0.x

The initial release is `0.1.0`. APIs are still developing, but compatibility within a minor
release line is intentional:

- **Patch (`0.1.0` → `0.1.1`):** compatible fixes, documentation and additive APIs that preserve
  existing callers. Keep public signatures, feature defaults, supported targets, minimum Rust
  version and documented behavior compatible. Check that additions do not break exhaustive
  matches, struct literals, trait implementations or other existing source patterns.
- **Minor (`0.1.x` → `0.2.0`):** changes requiring consumer action. This includes removing or
  changing public APIs, incompatible persisted representations, feature/default changes,
  dropping a supported target, raising the minimum Rust version, or upgrading a dependency
  such as egui when its exposed types become incompatible. Explain the before/after and migration.
- **`1.0.0`:** a separate decision that the public contracts are ready for long-term stability.
  After that, breaking changes require a major release; compatible additions use minor releases.

Documented invalid input can be rejected more strictly in a patch to fix a defect or security
issue. Call out any observable change. Do not use “0.x” or “bug fix” to silently break a valid,
documented workflow. App-owned settings schemas and migration policy remain the app's
responsibility; library releases do not automatically migrate consumer data.

For public egui APIs in `0.1.x`, keep the egui 0.36 compatibility line. The minimum Rust version
is 1.95. Compatible transitive updates still need validation and release-note coverage when
observable. Cargo's version-range rules do not select newer Git tags: changing a release pin
is always an explicit manifest edit.

## Support and scope

The newest minor line receives routine fixes. Important fixes to older lines are considered
case by case; there is no promise of maintaining every 0.x line or an LTS schedule. Existing
tags remain available so consumers can upgrade on their own schedule. Release notes identify
known limitations; a tag is not a claim that every driver, OS version or consuming app was tested.

Platform boundaries are crate-specific. See each crate's API/README and the release notes.
In particular, native printing needs the OS spooler, settings persistence is native-only, and
browser UI compatibility does not imply native services work in a browser. Consumers must test
their own save/close flows, accessibility, rendering and printing where they use those services.

## Preparing a release

1. Choose a reviewed commit on `main`. Inspect open defects, changes since the previous tag,
   crate metadata and any changed platform/dependency contracts. Update the shared version
   and lockfile when needed; the first release already uses `0.1.0`.
2. Add a dated `CHANGELOG.md` entry with the included crates, changes, compatibility requirements,
   migration steps and known limits. Update the README's recommended pin. Keep fixes and
   unrelated pending features out of the release preparation unless they block the baseline.
3. Run formatting, workspace Clippy with warnings denied, and workspace tests, both default
   and all features. The `Workspace` workflow runs these on Linux, macOS and Windows, requires
   Windows spooler regression tests, checks the minimum compiler on Linux, and checks the
   documented UI/settings WASM surface. All release jobs must pass for the candidate source.
   Repository-local build commands must also follow the host's storage/allocation rules.
4. Review consumer impact and existing platform evidence. Exercise affected native workflows
   when behavior changes; unit tests and cross-compilation cannot establish GUI or physical
   printer acceptance. Record limitations instead of extending the support claim beyond evidence.
5. Merge the preparation PR and verify the checks for the actual release commit. Create an
   annotated tag on that exact commit (`git tag -a vX.Y.Z FULL_SHA -m "craft-libs vX.Y.Z"`),
   push only that tag, and create a GitHub Release using that version's changelog entry.
   Tag-triggered CI should also pass. Do not publish crates as part of this Git-only release.
6. Verify that the remote tag resolves to the intended commit, the release notes are visible,
   and a small external consumer resolves and checks with the documented pin. Preserve the
   source identity, check results and release URL. Never repair a published tag by moving it.

The workflow validates source; it does not automatically tag or publish on every push.