From b5e52c86f1ab59d57faf7b8a467b105f370974fc Mon Sep 17 00:00:00 2001 From: Teakowa Date: Mon, 28 Sep 2026 15:49:30 +0800 Subject: [PATCH] docs: define the 1.x compatibility policy for catalog, behavior, and output changes Fixes #313 --- docs/compatibility-facades.md | 47 +++++++++++++++++++++++++++++++++++ docs/release.md | 3 +++ 2 files changed, 50 insertions(+) diff --git a/docs/compatibility-facades.md b/docs/compatibility-facades.md index adaebd11..2038d56a 100644 --- a/docs/compatibility-facades.md +++ b/docs/compatibility-facades.md @@ -101,3 +101,50 @@ The canonical program model (`Action`, `Value`, `Event`, `EventTeam`, `EventTarget`), `catalog::Kind`, source positions and spans, and values that consumers construct stay exhaustive. New Workshop content reaches them through catalog ids and `Call`, not new variants. + +## Versioning of catalog, behavior, and output changes + +`cargo-semver-checks` sees only the Rust API. Catalog content, parse results, +validation results, and emitted text also change between releases, and +consumers with a caret requirement pick up every minor release. From 1.0 on, +releases are versioned as follows. + +- **Major:** an incompatible change to the documented public Rust API, as + reported by `cargo-semver-checks`. +- **Minor:** + - catalog updates: added actions, values, heroes, maps, and settings; + changed parameters; new or changed locale spellings; corrections that + remove ids which were never native Workshop elements (such as [#299](https://github.com/wrightkit/workshop-rs/pull/299)); + - parse, validation, or emit changes that align behavior or output with the + live client (such as [#300](https://github.com/wrightkit/workshop-rs/pull/300) and [#303](https://github.com/wrightkit/workshop-rs/pull/303)); + - new public API; + - MSRV increases. +- **Patch:** fixes with no observable change to the parsed `Program`, emitted + text, validation results, or catalog content. + +Catalog corrections do not keep the removed id: the parser rejects it like any +other unknown id, matching the live client. + +Overwatch has not removed a native Workshop action or value so far; its updates +change parameters, spellings, and engine behavior instead. `workshop-rs` keeps +no legacy ids for that case. If a native element is ever removed, the catalog +follows the client and the release notes declare the removal as a breaking +behavior change; the maintainer decides at that point whether it ships in a +minor or a major release. + +The catalog dataset carries its own version, `catalog_version` in +`catalog::CatalogIdentity`, which changes with any dataset change independently +of the crate version. + +GitHub Release notes are generated from merged pull request titles, so the +title marks the kind of change. This applies to every pull request, before +and after 1.0: + +- catalog updates use `feat(catalog): ...`; +- other changes to parse, validation, or emit results use `feat(): ...` + rather than `fix`, and the pull request body has a `## Behavior change` + section describing the observable difference; +- `fix` is reserved for changes that qualify as a patch under the rules above. + +release-plz derives a minor release from `feat`, so these titles also select +the right version. diff --git a/docs/release.md b/docs/release.md index 0818087d..8a8640ae 100644 --- a/docs/release.md +++ b/docs/release.md @@ -121,6 +121,9 @@ listed in the The CLI crate, generated catalog data, test support, storage internals, and `#[doc(hidden)]` compatibility paths are outside this gate unless they are reachable through that documented API. +Catalog, parse, validation, and emit changes are outside this gate; how they +are versioned and labeled in release notes is defined in +[Versioning of catalog, behavior, and output changes](compatibility-facades.md#versioning-of-catalog-behavior-and-output-changes). Before 1.0, the job treats a `0.x` package as a major compatibility transition only when the pull request title uses a Conventional Commit breaking marker