CultLib/docs/semver-policy.md

Semantic Versioning Policy

Operator ruling, 2026-09-17: semantic versioning is policy for every package CultLib publishes, strictly. A release that removes or changes public surface incompatibly is a major bump, full stop — not a judgment call left to the person cutting the release.

This document says what "breaking" means for each kind of surface this repo actually ships, and how a release is checked against it. See docs/nuget-packaging.md for how the managed/Unity packaging mechanics work; this document is the versioning contract those mechanics must satisfy.

The scar

org.gamecult.cultlib 1.0.60 removed CultInspectorAssetPath — public API — and shipped as a patch bump. Its own changelog entry is titled "Breaking"; the version number said otherwise. A reviewer relying on the number alone would have missed it. This is recorded as history, not fixed by renumbering: 1.0.60 stays 1.0.60. This policy, and the check below, exist so the next one is caught before it ships instead of written up afterward.

Packages in scope

Package	Kind	Tag prefix	Published by
org.gamecult.cultlib	Unity UPM	cultlib-unity	scripts/build-unity-package.ps1, consumed by git tag
org.gamecult.caching.unity	Unity UPM	caching-unity	tagged directly (no build script; see "Coverage gaps")
org.gamecult.cultmath	Unity UPM	cultmath-unity	packages/cultmath/scripts/build-unity-package.ps1, consumed by git tag
@gamecult/cultcache-ts	npm	cultcache-ts	.github/workflows/publish-packages.yml
cultcache-py	PyPI	cultcache-py	.github/workflows/publish-packages.yml
cultnet-py	PyPI	cultnet-py	.github/workflows/publish-packages.yml
cultmesh-py	PyPI	cultmesh-py	.github/workflows/publish-packages.yml

Rust crates are consumed as pinned git revisions (see publish-packages.yml's own header comment) and are out of scope for tagged-release semver policing; a Cargo.toml version still exists and should follow this policy by convention, but nothing in this repo checks it mechanically today.

Tag naming stays <package>-v<version> for every package above, matching the prefixes already in use.

What counts as breaking

Semver's ordinary rule — additive is minor or patch, anything a consumer's existing code or data can no longer rely on is major — applies per surface as follows.

Managed public API (org.gamecult.cultlib, NuGet packages, cultmath)

Breaking: removing or renaming a public type/member, changing a public member's signature or observable behavior in an incompatible way, tightening a public contract (new required parameter, narrowed accepted input), or moving a type across assemblies/namespaces without a compatible forwarder.

Not breaking: adding a new public member, type, or overload; widening an accepted type; deprecating (marking obsolete) without removing.

Unity package inspector attributes (org.gamecult.cultlib,

org.gamecult.caching.unity)

These ship as ordinary public API by the rule above, but get their own callout because they are easy to mistake for "just editor tooling": an attribute class, its constructor shape, and the serialized value shape it reads/writes are all public surface a consumer's [CultInspectorX(...)] usage and serialized scene/prefab data depend on. Removing or renaming an attribute, or changing what it expects a annotated member's persisted value to look like (as CultInspectorAssetPath to CultInspectorAssetGuid did in 1.0.60) is breaking.

Persisted wire format / store compatibility (CultCache)

Governed by src/GameCult.Caching/Contracts/cultcache-schema-compatibility.md and cultcache-persistence-format.md — read those for the authoritative rules. In semver terms: anything those documents classify as hard rejection (type change, reference/value change, one-vs-many change, target schema change, name/index lookup semantics change, a persisted schema with no compatible local candidate) is breaking for any package that reads or writes the format. Anything classified as soft-migratable drift (compatible schema id drift, an ignorable missing slot, a defaultable missing slot) is not breaking on its own, but changing what counts as soft-migratable — loosening or tightening the drift rules themselves — is breaking for whichever package owns that classification logic.

CultNet protocol surface

Breaking: a wire-incompatible change to a CultNet message, frame, or handshake shape; removing or repurposing a message type or field that another runtime's implementation depends on; changing routing, authority, or trust semantics such that a peer built against the previous protocol version misbehaves rather than cleanly failing. Additive, backward-compatible framing changes (a new optional field a receiver may ignore) are not breaking.

Native bridge exported functions (GameCult.Mesh.Quic.Native)

Breaking: removing or changing the signature/ABI of a CULTMESH_API (extern "C") exported function, or changing an exported function's behavior such that the existing managed P/Invoke caller (GameCult.Mesh.Quic.Native's C# side) or Rust caller (cultmath-core's equivalent #[no_mangle] extern "C" surface) no longer gets what it asked for. Swapping the underlying TLS/QUIC implementation (as 1.0.60 did, Schannel to OpenSSL MsQuic) is not breaking by itself as long as the exported v1 functions keep their signatures and behavior — 1.0.60's actual breaking change was the inspector attribute removal, not the bridge swap, and its changelog correctly filed the bridge swap under "Changed" rather than "Breaking".

Pre-1.0 packages

A package at 0.y.z (currently org.gamecult.cultmath, at 0.2.x) uses the standard pre-1.0 convention: MAJOR stays 0 during initial development, so MINOR carries what MAJOR means once the package reaches 1.0.0. Concretely:

• a breaking change bumps MINOR (and resets PATCH to 0);
• a non-breaking change bumps PATCH.

Leaving 0.y.z for 1.0.0 is a deliberate, separate decision (the API is now considered stable), not something the checker infers on its own.

What a release changelog entry must contain

Every published package keeps a CHANGELOG.md beside its manifest (unity/org.gamecult.cultlib/CHANGELOG.md and src/GameCult.Unity/Assets/Caching/CHANGELOG.md are the existing precedent). Each release adds a ## [<version>] section containing:

• a category subsection per change (### Added, ### Changed, ### Fixed, etc., following Keep a Changelog style);
• ### Breaking — this exact heading, this exact spelling — for any change that meets the "what counts as breaking" rules above. This heading is not decorative: the CI check below greps for it by name.
• enough detail that a consumer can tell what to change, in the style of the 1.0.60 entry (name the removed/changed symbol and its replacement).

A version with no changelog entry at all fails the check below, the same as a mislabelled one — an undocumented release is not a smaller sin than a mislabelled one.

Enforcement

scripts/check-changelog-semver.mjs is the mechanical check. Given a package name, its CHANGELOG.md path, the version being released, and a git tag prefix, it:

1. resolves the previous published version from the highest existing <prefix>-v* tag older than the version being released. A first release is never inferred: with no such tag, or with tags that cannot be read (a --cwd that is not a git repository), the check refuses unless the caller declares --first-release; declaring it while an earlier tag exists is refused too. A tag for the version being released does not exempt it: there is no "already published" skip, so callers do not run the check for a version they are only rebuilding;
2. requires a ## [<version>] changelog entry to exist at all;
3. classifies the version bump (major/minor/patch) against the previous version, refusing anything that is not exactly the next version in some lane — a skip, a reversal, or a repeat are all refused, not just wrong bump sizes;
4. when the release script supplies built assemblies (below), treats the release as breaking if the public API measurably lost or changed a member against the previous tag, whether or not the changelog says so; a measured break with no ### Breaking section is refused, naming the count, the first diagnostics, and the heading that must declare them;
5. if the release is breaking (a ### Breaking section, a measured break, or both), requires the bump to be at least major (or, pre-1.0, at least minor); a ### Breaking section with nothing measured is valid, because behavioural breaks are invisible to a signature comparison;
6. fails loudly, naming the package, the previous and new version, and (when relevant) the changelog heading or the measured diagnostics that triggered the requirement.

Additions are never a rule: adding a public member is not breaking (see above), and the check neither refuses nor demands a bump for one.

Measured input

The Unity release scripts pass --api-baseline-path <repo-relative directory of tracked DLLs> and one --api-built <dll> per assembly they built (plus --api-refs <dir> for directories that hold the built assemblies' dependencies, and --api-new <dll name> for an assembly that is new in this release). For each built DLL the checker reads its namesake under the baseline path at the previous tag as a git blob (no worktree, no network, unaffected by what the working tree tracks now) and compares public API with Microsoft.DotNet.ApiCompat.Tool. Each CPnnnn diagnostic is one measured break. A GameCult.* assembly the previous tag tracked and the build no longer produces is itself a measured break.

Measuring nothing is a refusal, never a pass. The check refuses, naming what is missing, when the previous tag tracks no DLL under the baseline path (a wrong or moved path, or a tag that predates it); when a built assembly has no namesake at the tag and was not declared with --api-new; when an assembly declared new is already tracked; and when the tool fails to measure (not installed, an unreadable assembly, a crash: a non-zero exit with no diagnostic line). A first release declared with --first-release measures nothing.

The tool and the NETStandard.Library.Ref 2.1.0 reference assemblies are pinned in scripts/api-gate/ (.config/dotnet-tools.json and ApiRefs.csproj) and restored there by the check itself, so a release does not depend on any other tool in the repository's manifest. NuGet is needed until both are cached under scripts/api-gate. Both sides of every comparison resolve netstandard types through those reference assemblies, and the new side also through the built DLL's own directory and every --api-refs directory. No suppression file is kept: a suppression would be a second, silent declaration of a break, so a break is declared only under ### Breaking.

A passing measured run prints that unmeasured changes still need declaring.

Unmeasured changes

ApiCompat does not report these changes to a public member, and the check therefore passes them. Each is a breaking change under the rules above and is declared under ### Breaking, as behavioural breaks are:

• a member gaining or losing static;
• a parameter gaining or losing ref, out or in;
• a const field's value changing;
• an enum member's underlying value changing;
• a field gaining or losing readonly;
• a default parameter value changing.

The release scripts run the check once the assemblies under judgement exist, after the build and before anything is copied into the package.

Run it directly: node scripts/check-changelog-semver.mjs --package <name> --changelog <path> --version <x.y.z> --tag-prefix <prefix> (CI's TS and Python jobs and verify-caching-unity-release.ps1 pass no measured input). Its own tests live in scripts/check-changelog-semver.test.mjs (node --test scripts/check-changelog-semver.test.mjs).

It is wired into:

• .github/workflows/publish-packages.yml, right after each job's existing "tag matches manifest version" check, for cultcache-ts, cultcache-py, cultnet-py, and cultmesh-py;
• scripts/build-unity-package.ps1, for org.gamecult.cultlib;
• packages/cultmath/scripts/build-unity-package.ps1, for org.gamecult.cultmath;
• scripts/verify-caching-unity-release.ps1, for org.gamecult.caching.unity.

Coverage gaps

publish-packages.yml only triggers on cultcache-ts-v*, cultcache-py-v*, cultnet-py-v*, and cultmesh-py-v* tag pushes — it does not build or gate the Unity UPM packages at all; those are consumed directly by git tag (unity/org.gamecult.cultlib, packages/cultmath/unity/org.gamecult.cultmath, src/GameCult.Unity/Assets/Caching), so a workflow trigger on their tags cannot be added to that file without also giving it a reason to check out and build Unity content it currently has no job for. The check is instead wired into the scripts that already run at Unity-package release time: build-unity-package.ps1 and packages/cultmath/scripts/build-unity-package.ps1 already verify version consistency between the built assembly and package.json, so the semver check runs alongside that as one more release gate. org.gamecult.caching.unity has no build script at all today — it is pure C# source tagged directly with no compile step — so scripts/verify-caching-unity-release.ps1 exists solely to run this check before that package is tagged; it is not a build script and does not become one.

None of this is enforced by a git hook or branch protection rule: it runs when someone remembers to run the Unity release scripts, the same way the existing assembly-version check does. A tag pushed by hand without running the release script bypasses both checks equally; closing that gap is a CI trigger on tag push for the Unity packages, not something this change adds.

What stays unmeasured: behaviour behind an unchanged signature, wire formats, native exports of the QUIC bridge, and the Caching Unity package's source (it has no assembly). Those rest on the ### Breaking declaration.

Rust crates (consumed as pinned git revisions, not tagged releases in the usual sense) and the CultNet protocol surface itself (no automated wire compatibility test currently gates a release) are policy by convention only — described above, not mechanically checked. Extending the checker to a Rust crate's Cargo.toml/CHANGELOG.md or to an automated CultNet interop compatibility gate is future work, not part of this change.

@gamecult/cultcache-ts, cultcache-py, cultnet-py, cultmesh-py, and org.gamecult.cultmath currently have no CHANGELOG.md file at all. This is a real, pre-existing gap, not something introduced by this policy: their next tagged release will fail the new check for exactly that reason ("no changelog entry for version X") until each package's CHANGELOG.md exists. That failure is intended — a release with no changelog is not a smaller problem than a mislabelled one — but it does mean the very next release of any of these five packages needs a CHANGELOG.md created first. Backfilling changelog content for their past releases is not part of this change: it would mean inventing release-note prose for history this pass has no first-hand knowledge of, which is worse than leaving the gap named.