Versioning

The build systems use semantic versioning defined by semver 2.0.

Immutability of Versions

Once a value is distributed with a version, the value should not change. Violations mean that consumers will have incorrect and outdated values in their caches.

Comment or formatting edits to a values.json or a values.lua that leave behavior identical may safely be edited on the same distributed version.

Immutability binds once a consumer of the distributed package imports the package. Before then a release is a candidate that only the producer imports, and testing the candidate from its release is the only way to exercise the consumer-side import path. The producer may repair a defect found in a candidate, delete the candidate tag and its release, and re-release the same versions.

Sealing is append-only and gated at the distribution level; see Increased Minor Numbers.

Increased Patch Numbers

Example: 0.3.0 to 0.3.1

A behavior-preserving repair should increase the patch number. Existing consumers can keep their existing versions and opt-in to the repair by importing a release that carries the new version.

Even though distributions are sealed, an increased patch number does not require a new signify key.

Increased Minor Numbers

Example: 0.3.0 to 0.4.0

A new capability should increase the minor number:

• Adding a new rule to a scriptmodule (values.lua), or a new scriptmodule, is a new capability.
• Adding a new module to a values.jsonc, or a new values.jsonc, is a new capability.

A distribution may add to its sealed set, either a brand-new module or a strictly higher MAJOR.MINOR version of an already-sealed module, only when the distribution's own MAJOR.MINOR is strictly higher than the latest sealed release. A release within an already-sealed MAJOR.MINOR line can neither add modules nor add module MAJOR.MINOR versions.

Sealing constrains what a consumer of an imported distribution may reference. It does not constrain the producer's own local package. Resolution for a local package, the package a distribute builds or a package a producer trusts locally, is independent of whether a distribution of that package is imported: a module the imported distribution did not seal resolves through the producer's own declaration, the same behavior the producer sees when no distribution of the package is imported at all. This matters when a producer builds a new release on top of a restored previous release. An internal module the previous release did not seal, one reached only through a run command so its trace is a dependency rather than a sealed output, still builds from the producer's declaration. The same holds when the producer bumps a module the previous release DID seal to a new MAJOR.MINOR line: the local package builds the new line from its own declaration even though the imported distribution seals only the lower line, whereas a consumer of that imported distribution still may not reference the unsealed line.

Minor numbers require a new signify key when the new minor number has not already been sealed by the previous distribution. In other words, a small number of minor number increases will eventually lead to the producer having to create a new set of sealed signify keys; that requires the producer to establish that they have possession of the secret key.

That is a security property: new capabilities increase the security surface, and versioning requires the producer to eventually authenticate their ownership of the changes.

Consumers opt in by referencing the new version; existing references keep their existing behavior.

Increased Major Numbers

Example: 0.3.0 to 1.0.0

A backwards-incompatible change should increase the major number.

Major numbers, like minor numbers, require a new signify key when the new major number has not already been sealed by the previous distribution.

Consumers opt in by referencing the new version; existing references keep their existing behavior.

Nonstandard Semantic Versions

Often values do not have a natural semantic version.

An example would be a privacy policy contained in a bundle module YourOrg_Std.StringsForWebSiteAndPrograms.PrivacyPolicy. YourOrg_Std.StringsForWebSiteAndPrograms.PrivacyPolicy@1.0.20250904 could be used for the 2025-09-04 privacy policy.