API Compatibility and Semantic Versioning

This article defines the public API compatibility promise for the stable AsiBackbone package family and documents how semantic versioning applies after stabilization.

It complements the historical stable API review tracked in issue #13. The 2.0.0 release moved public package IDs and namespaces from CDCavell.AsiBackbone.* to AsiBackbone.*. The 3.0.0 release established the prior binary assembly identity, 4.0.0, 5.0.0, and 6.0.0 each started a previous stable line while preserving the existing package IDs and namespaces, and 7.0.0 starts the current 7.x stable line maintained on main.

Note

Additive public API or package surface should use a minor version bump even when the change is backward-compatible. Patch releases should be reserved for fixes, documentation, packaging, tests, and implementation hardening that do not expand the stable public surface.

Compatibility promise within a stable major line

Packages identified as stable are expected to preserve their documented public API surface for consumers within the same major version. This promise applies within the current 7.x stable line maintained on main, and it applied in the same way within the earlier 4.x, 5.x, and 6.x stable lines.

The compatibility promise applies to:

public types and members exposed by stable packages;
public namespaces intended for consumer use;
documented extension points and service registration methods;
documented option shapes and default behavior;
durable artifact shapes that are explicitly described as stable, including their schema version where applicable;
package boundaries and dependency direction described as stable for the released package family.

The promise does not mean implementation internals will never change. Internal code, private members, tests, documentation wording, samples, and non-public implementation details may change in minor or patch releases when the public contract remains compatible.

Automated public API baseline gate

Stable managed package APIs are protected by committed baselines under eng/api-baseline/. CI builds the DocFX managed-reference surface and runs ./scripts/Validate-PublicApiBaseline.ps1; an unreviewed public addition, removal, enum-value change, or signature/declaration change fails the gate.

The baseline update is intentionally reviewable in source control. For an approved API change, classify the SemVer impact first, inspect the failing baseline diff, then run ./scripts/Validate-PublicApiBaseline.ps1 -Update and commit the resulting eng/api-baseline changes in the same pull request. Updating the baseline does not waive the versioning rules: additive stable API requires at least a minor release, while a breaking stable API change requires a major release and migration guidance.

AsiBackbone.Templates is excluded from the managed-assembly baseline because it is a content-only dotnet new package; its released contract remains protected by template smoke validation. The complete included/excluded surface and local workflow are documented in API Baseline and Architecture Boundary Checks.

Stable package scope by release

Stable compatibility is package-specific. A package becomes part of the stable contract when it is released as a stable package and documented as part of the stable package family.

Original `1.0.0` stable family

The initial stable 1.0.0 package family established the first compatible 1.x baseline:

Package	Stable role
`AsiBackbone.Core`	Framework-neutral governance primitives, decisions, constraints, actor context, decision receipt, acknowledgment, capability-token abstractions, and operation results.
`AsiBackbone.AspNetCore`	ASP.NET Core host adapters for actor context, request correlation, HTTP result mapping, and acknowledgment challenge support.
`AsiBackbone.Storage.InMemory`	Non-durable in-memory storage helpers for tests, samples, and local validation.
`AsiBackbone.EntityFrameworkCore`	EF Core model configuration and host-owned persistence integration.

Expanded `1.1.x` and `1.2.x` stable family

The 1.1.x and 1.2.x releases expanded the stable 1.x contract with compatible additive package surfaces including DependencyInjection, Testing, Templates, Analyzers, OpenTelemetry, Signing.LocalDevelopment, and Signing.ManagedKey. 1.2.1 was the final stable patch release for the compatible 1.x line before the package/namespace rename.

`2.x` stable family

The 2.0.0 release established the simplified AsiBackbone.* package and namespace identity after the public rename from CDCavell.AsiBackbone.*. 2.0.1, 2.0.2, 2.1.0, 2.1.1, 2.2.0, 2.2.1, and 2.3.0 preserved that package/namespace boundary while adding compatible package and host-facing surfaces.

`4.x` stable family

4.0.0 established the previous stable line. It preserved the AsiBackbone.* package IDs and namespaces while advancing the binary assembly identity to 4.0.0.0 and changing the outbox claim-leasing default.

`5.x` stable family

5.0.0 established the previous stable line, and 5.2.0 was its final minor release. It preserved the AsiBackbone.* package IDs, namespaces, the net10.0 target, and binary assembly identity 5.0.0.0, and began the ASIB900 deprecation window completed in 6.0.0.

`6.x` stable family

6.0.0 established the previous stable line. It preserved the AsiBackbone.* package IDs, namespaces, and the net10.0 target while advancing the binary assembly identity to 6.0.0.0. It renamed public types and helper members to plain-language semantic names, removed the members whose 5.x deprecation windows completed, and changed verification defaults, the signature-input wire format, and in-memory use-store retention. See Upgrade from 5.x to 6.0.

Current `7.x` stable family

7.1.0 is the current stable release on main. The 7.x line preserves the AsiBackbone.* package IDs, the net10.0 target, and binary assembly identity 7.0.0.0. Version 7.1 adds analyzer guidance and deprecates retained compatibility APIs through warnings and documented replacements without removing them or changing their runtime behavior. See 7.1.0 Release Notes and Upgrade from 6.x to 7.0.

Package	`7.x` stable role
`AsiBackbone.Core`	Framework-neutral governance primitives and durable artifact contracts for the current `7.x` line, including policy evaluation, governance decisions, threat-model contributor hooks, metadata budget validation helpers, constraint-exception denial behavior, governed execution-to-mutation accountability receipts, capability-proof trust pinning, explicit capability-grant validation profiles, and canonical capability-grant payload construction.
`AsiBackbone.DependencyInjection`	Explicit builder facade and host-selected provider registration composition path.
`AsiBackbone.Storage.InMemory`	Non-durable storage helpers for tests, samples, local validation, lifecycle events, and outbox proof paths.
`AsiBackbone.EntityFrameworkCore`	EF Core host-owned persistence helpers for audit, acknowledgment, lifecycle, JSON metadata storage guidance, and outbox records.
`AsiBackbone.AspNetCore`	ASP.NET Core host adapters, endpoint governance, endpoint-governance metadata mode, strict-governance profile helpers, development diagnostics, endpoint fast-abort metadata, conservative actor-type claim trust controls, startup/configured-options validation, and hosted outbox drain integration.
`AsiBackbone.Testing`	Test-only harness helpers for deterministic governance and package-wiring tests.
`AsiBackbone.Templates`	Developer-experience `dotnet new` templates for governed ASP.NET Core host scaffolding.
`AsiBackbone.Analyzers`	Build-time analyzer safety rails, including production-signing configuration guidance.
`AsiBackbone.OpenTelemetry`	Released OpenTelemetry governance emission provider.
`AsiBackbone.Signing.LocalDevelopment`	Local-development signing and verification for tests, samples, and wiring proof paths only.
`AsiBackbone.Signing.ManagedKey`	Managed-key signing adapter boundary where the host supplies the actual managed-key client and operational controls. Production-oriented registration fails closed by default when signing cannot complete.

Stable package status does not imply that every future provider idea is stable. Event Hubs, Purview, Azure-specific SDK adapters, Aspire runtime packages, robotics, immutable storage, and additional provider packages remain outside the stable contract unless separately reviewed and released as stable packages.

What counts as a breaking change

A breaking change should require a new major version when it affects a stable package contract. Examples include:

removing or renaming a public type, member, enum value, interface, namespace, or package;
changing public method signatures, constructor signatures, generic constraints, or return types;
changing documented default behavior in a way that can alter consumer outcomes;
making previously optional configuration required;
changing stable serialized or persisted artifact shapes without a compatible reader, migration path, or schema-versioned transition;
changing service registration behavior in a way that breaks existing host startup code;
changing package dependency direction or adding a framework/provider dependency that violates a documented package boundary;
changing documented exception behavior where callers are expected to handle that behavior;
converting a host-owned integration responsibility into a package-owned requirement without a compatible opt-in path.

A change is not usually breaking when it only adds new optional APIs, adds new optional configuration, improves implementation behavior without changing the public contract, fixes a bug to match documented behavior, or updates documentation and samples.

Semantic versioning expectations

AsiBackbone follows Semantic Versioning expectations after stabilization:

Version segment	Expected behavior
Major	May include intentional breaking changes to stable public APIs, stable package boundaries, binary assembly identity, or stable artifact contracts. Breaking changes should be documented with migration notes.
Minor	Adds backward-compatible public APIs, options, adapters, packages, or features. Existing stable APIs should continue to compile and behave compatibly.
Patch	Fixes bugs, documentation issues, packaging issues, or implementation defects without adding breaking public API changes. Patch releases can also clarify documentation and strengthen tests.
Preview suffix	Indicates packages or features that are still under review and may change before stable release.

For future releases, additive public API or package changes should be grouped into a minor release even when they are opt-in and backward-compatible.

Deprecation and major-release policy

This policy applies to changes made after 7.0.0. Releases 4.0.0 through 7.0.0 shipped within a short period, and some renamed or removed members in that span had no forwarding window. The rules below make the stable contract predictable for consumers who persist governance evidence or build long-lived integrations.

Deprecation before removal

A stable public type, member, namespace, option, extension point, or documented default may be removed or renamed only in a major release, and only after it has been deprecated in a published release of the preceding major line.

A deprecation is complete only when all of the following are true:

the member carries [Obsolete] as a compiler warning, not an error, with a stable ASIB9xx diagnostic ID and a message that names the replacement;
the replacement API ships in the same release as the deprecation, so consumers can migrate before the removal release exists;
a rename is delivered as an additive replacement plus an obsolete forwarding member, not as a removal-only change;
the changelog, release notes, and an ASIB9xx migration article describe the replacement and the earliest major version in which removal may occur.

Minimum deprecation window

A deprecated member remains available for at least 90 days after the first published release that deprecates it and through at least one subsequent published minor release of the same major line. Both conditions must be met before the removal release is tagged.

Durable contracts follow the same window. Changes to persisted column names, serialized property names, canonical wire values, and enum numeric values require a published migration path, and where practical a compatible reader, before the release that removes the old shape.

Major-release spacing

At most one major release may be published in any rolling six-month period.
Following 7.0.0 (published 2026-09-26), the next major release will not be tagged before 2027-03-26.
A planned major release is announced in GitHub Discussions at least 30 days before it is tagged. The announcement lists every intended breaking change and links the deprecations already published for it.

Preceding major line after a new major release

When a new major release is published, the preceding major line receives fixes for vulnerabilities rated High or Critical for six months after the new major release date. When a fix cannot be backported compatibly, the project publishes a security advisory with host-side mitigation guidance instead. Other reports against the preceding line are handled on a best-effort basis.

Security exception

When an existing behavior is itself a High or Critical vulnerability and cannot be corrected compatibly, a breaking fix may ship before the deprecation window or the major-release spacing would otherwise allow. The release must identify the security justification and the related advisory, and must still include migration guidance and a host-side mitigation for consumers who cannot upgrade immediately. Fail-closed default changes made for security reasons fall under this exception; naming and ergonomic changes do not.

Checking a proposed break

Before a breaking change is merged for a future major release, confirm that:

the replacement and the [Obsolete] deprecation are already published in the current major line;
the minimum deprecation window will have elapsed by the planned tag date;
the major-release spacing and the 30-day announcement requirement are satisfied, or the security exception is documented;
the migration article and changelog entry exist.

Assembly version policy

For the stable 7.x package line, AsiBackbone keeps AssemblyVersion fixed at 7.0.0.0 for compatible minor and patch releases. NuGet package Version, FileVersion, and InformationalVersion continue to move with each package release.

Expected stable-line behavior:

Release	Package `Version`	`AssemblyVersion`	`FileVersion`	`InformationalVersion`
`1.0.0`	`1.0.0`	`1.0.0.0`	`1.0.0.0`	`1.0.0+...`
`1.1.0`	`1.1.0`	`1.0.0.0`	`1.1.0.0`	`1.1.0+...`
`1.2.0`	`1.2.0`	`1.0.0.0`	`1.2.0.0`	`1.2.0+...`
`1.2.1`	`1.2.1`	`1.0.0.0`	`1.2.1.0`	`1.2.1+...`
`2.0.0`	`2.0.0`	`2.0.0.0`	`2.0.0.0`	`2.0.0+...`
`2.0.1`	`2.0.1`	`2.0.0.0`	`2.0.1.0`	`2.0.1+...`
`2.0.2`	`2.0.2`	`2.0.0.0`	`2.0.2.0`	`2.0.2+...`
`2.1.0`	`2.1.0`	`2.0.0.0`	`2.1.0.0`	`2.1.0+...`
`2.1.1`	`2.1.1`	`2.0.0.0`	`2.1.1.0`	`2.1.1+...`
`2.2.0`	`2.2.0`	`2.0.0.0`	`2.2.0.0`	`2.2.0+...`
`2.2.1`	`2.2.1`	`2.0.0.0`	`2.2.1.0`	`2.2.1+...`
`2.3.0`	`2.3.0`	`2.0.0.0`	`2.3.0.0`	`2.3.0+...`
`3.0.0`	`3.0.0`	`3.0.0.0`	`3.0.0.0`	`3.0.0+...`
`3.0.1`	`3.0.1`	`3.0.0.0`	`3.0.1.0`	`3.0.1+...`
`3.1.0`	`3.1.0`	`3.0.0.0`	`3.1.0.0`	`3.1.0+...`
`3.2.0`	`3.2.0`	`3.0.0.0`	`3.2.0.0`	`3.2.0+...`
`3.2.1`	`3.2.1`	`3.0.0.0`	`3.2.1.0`	`3.2.1+...`
`3.2.2`	`3.2.2`	`3.0.0.0`	`3.2.2.0`	`3.2.2+...`
`3.2.3`	`3.2.3`	`3.0.0.0`	`3.2.3.0`	`3.2.3+...`
`4.0.0`	`4.0.0`	`4.0.0.0`	`4.0.0.0`	`4.0.0+...`
`5.0.0`	`5.0.0`	`5.0.0.0`	`5.0.0.0`	`5.0.0+...`
`5.1.0`	`5.1.0`	`5.0.0.0`	`5.1.0.0`	`5.1.0+...`
`5.2.0`	`5.2.0`	`5.0.0.0`	`5.2.0.0`	`5.2.0+...`
`6.0.0`	`6.0.0`	`6.0.0.0`	`6.0.0.0`	`6.0.0+...`
`7.0.0`	`7.0.0`	`7.0.0.0`	`7.0.0.0`	`7.0.0+...`
`7.1.0`	`7.1.0`	`7.0.0.0`	`7.1.0.0`	`7.1.0+...`

Before cutting stable releases, release validation should verify that AssemblyVersion, FileVersion, InformationalVersion, package metadata, release notes, and repository tags match this policy.

Durable artifact and schema-version policy

Stable persisted or exported governance artifacts should carry an explicit schema/version field when they may be stored or consumed outside the running process. See Schema Versioning for artifact-specific guidance.

Schema versioning does not replace package versioning. Package versions describe the released library. Schema versions describe durable payload shapes that may outlive a single package release.

Additive artifact fields are normally acceptable in a compatible minor release when existing readers can continue operating or when schema-versioned handling is documented. Incompatible durable shape changes should use schema-version guidance, migration documentation, and a major-version boundary when needed.

Provider and future package guidance

Released provider packages have their own stable contract within the compatible 7.x line once they are published as stable packages. Documentation should state whether each package is stable, preview, experimental, design-only, strategy-only, sample-only, or host-owned integration guidance.

Release readiness checklist reference

Before cutting a stable release or stable package-family expansion, the release readiness checklist should confirm that:

the stable package list is identified;
public APIs for stable packages are reviewed for naming, namespace, dependency direction, and extension-point clarity;
the committed public API baseline matches generated DocFX output, and any intentional baseline update is accompanied by an explicit SemVer classification;
breaking changes found during review are resolved before release or captured for a future major version;
stable serialized artifacts have documented schema-version behavior;
the AssemblyVersion strategy is resolved and reflected in build metadata;
stable provider packages are clearly distinguished from future/design-only provider pages;
preview, strategy-only, design-only, or sample-only packages are not implied to be part of the stable contract;
the changelog and release notes include the compatibility promise and migration guidance where needed.

Table of Contents