Release and Versioning Guidelines

Release and versioning rules are defined immediately after the README. A product must be identifiable, reproducible, upgradeable, and recoverable before onboarding or core functionality is treated as stable.

Required outcome

For every distributed version, a user or operator must be able to determine:

• the exact product version;
• the exact source revision;
• how the artifact was built and published;
• whether it is compatible with their current environment and data;
• how to upgrade;
• how to roll back or recover;
• which behavior changed from the previous version.

Versioning policy

Products must use Semantic Versioning unless a documented domain constraint requires a different scheme.

Given MAJOR.MINOR.PATCH:

• MAJOR changes indicate an incompatible public contract;
• MINOR changes add backward-compatible capability;
• PATCH changes correct behavior without intentionally breaking compatibility.

While MAJOR is zero the product has no stable contract yet, and the MINOR slot carries the compatibility boundary instead:

• a change that would advance MAJOR advances MINOR, resetting PATCH;
• a change that would advance MINOR advances PATCH.

So a breaking change to 0.1.0 produces 0.2.0, not 1.0.0, and both an additive and a corrective change produce 0.1.1. Advancing MAJOR to one is a deliberate act declaring the contract stable, never a side effect of the first break.

This means a 0.x product cannot distinguish an additive change from a corrective one by its version alone, because it has no third slot to spend. The change class must still be recorded in the release notes, so the reason for a release survives a number that cannot express it.

Pre-release identifiers may be used for builds that are not production contracts. Build metadata may identify a build but must not replace the canonical version.

The policy must define what counts as a public contract, including:

• CLI commands and output intended for automation;
• API schemas and protocols;
• configuration formats;
• stored data and state layouts;
• artifact formats;
• extension and integration interfaces;
• documented operational behavior.

Single source of truth

The version must have one canonical source in the repository. Build scripts, binaries, packages, installers, release manifests, and documentation must derive from it.

Do not maintain independent version values that can drift. A release must fail rather than publish artifacts with conflicting versions.

The same applies to the rule that decides the version change. It must have one implementation shared across products, not one per repository. A product supplies the two things only it can know — its public surface, and any breakage that surface cannot show — and takes the class and the next version from the shared rule.

A rule copied per repository drifts silently, because nothing fails when two copies disagree: each release looks correct in isolation. This is not a hypothetical failure mode. Before it was consolidated, the same rule existed in three products at once and the copies disagreed both about what advances MINOR and about what a breaking change does while MAJOR is zero.

Source and artifact identity

Every release artifact must include or expose:

• product name;
• canonical version;
• source commit identifier;
• target platform and architecture;
• build timestamp when operationally useful;
• artifact digest;
• build or provenance record.

A published version must resolve to immutable bytes. Rebuilding or replacing an existing version with different content is prohibited.

Examples are versioned product artifacts. A release must ship or link to the example set from the same source revision, and every example must declare or inherit the compatible product version. An example from a mutable branch must not be presented as instructions for an immutable release.

Moving labels such as latest may exist for discovery, but production installation and rollback must resolve an immutable version and digest.

Release channels

Define explicit channels such as:

• development;
• nightly or edge;
• preview, beta, or release candidate;
• stable;
• long-term support, when applicable.

For each channel, document:

• intended audience;
• stability guarantee;
• promotion criteria;
• retention period;
• upgrade and rollback expectations;
• whether automatic upgrades are permitted.

Promotion should reuse the same verified artifact whenever possible. Rebuilding separately for each channel weakens provenance.

Repository ownership and product independence

Every independently operated product must own its complete release path in its canonical repository:

• the repository builds and publishes its own artifacts;
• its immutable source tag and release record live in that repository;
• its artifacts use a product-owned registry package or GitHub Releases channel;
• its publisher credential is scoped to that repository and channel;
• its installers resolve only that product's namespace, version, platform, and digest;
• its rollback path does not depend on another Wisent product being installed or available.

A product must not use another product's release, deployment, storage, or secret namespace as its mandatory distribution channel. Shared organization tooling may calculate versions, provide reusable workflow code, or aggregate discovery metadata, but it must not own the released bytes or become a runtime prerequisite. Each repository invokes shared tooling independently and retains its own publication authority.

Cross-product bundles and adapters are optional consumers of already published product contracts. Removing one product may remove its integration or add-on, but must not prevent another product from installing, starting, upgrading, rolling back, or recovering. A mirror or moving discovery alias may improve availability, but the canonical immutable coordinate and digest remain product-owned.

Release process

A release process must define:

1. the source revision selected for release;
2. the version change;
3. compatibility and migration review;
4. artifact construction;
5. provenance, signing, and digest generation;
6. publication to an immutable location;
7. release-note publication;
8. installation or deployment verification;
9. promotion between channels;
10. rollback readiness.

The process must be repeatable and owned. Manual steps must be documented, observable, and minimized.

Release notes

Every user-visible release must explain:

• added capabilities;
• changed behavior;
• corrected defects;
• removed or deprecated behavior;
• security-relevant changes;
• configuration changes;
• data or state migrations;
• compatibility requirements;
• operator actions required before or after upgrade;
• known limitations.

Release notes must describe user impact, not only commit titles.

Compatibility and migrations

Before release, define compatibility across:

• clients and servers;
• control plane and workers;
• old and new configuration;
• persisted state;
• plugins or integrations;
• rolling or mixed-version deployments.

Every migration must state:

• preconditions;
• whether it is forward-only or reversible;
• backup requirements;
• expected duration and service impact;
• failure behavior;
• resume or retry behavior;
• rollback procedure.

A release must not silently reinterpret durable data in an incompatible way.

Upgrade and rollback

The supported upgrade path must be explicit. If intermediate versions are required, list them. If downgrade is unsupported after a migration, state that before the upgrade begins.

Rollback instructions must identify:

• the artifact to restore;
• compatible state or schema versions;
• required backups or snapshots;
• how to prevent two versions from mutating the same state concurrently;
• how successful recovery is confirmed.

Security and access

Release publication must use least-privilege credentials. Build credentials, signing credentials, and runtime credentials must remain separate.

Published artifacts should be signed or otherwise verifiable. Installers must verify the selected version and artifact digest before execution.

Prohibited patterns

Do not:

• use a mutable branch as a production release coordinate;
• overwrite an existing released version;
• infer version solely from local Git state at runtime;
• publish artifacts without source provenance;
• mix unrelated breaking changes into a patch release;
• perform undocumented data migrations;
• call a build stable without a defined rollback path;
• expose a “latest” installer that cannot report the immutable version selected.

Completion gate

The release and versioning stage is complete only when:

• the version policy and public-contract boundary are documented;
• one canonical version source exists;
• artifacts are immutable and attributable to source;
• the canonical examples are attributable to the same version and source;
• release channels and promotion rules are defined;
• release notes have a required format;
• compatibility and migration rules are explicit;
• upgrade and rollback procedures are actionable;
• onboarding can install an exact, verifiable release without inventing release mechanics.