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 started the current 2.x line because the public package IDs and namespaces moved from CDCavell.AsiBackbone.* to AsiBackbone.*. 2.0.1 and 2.0.2 preserved that boundary through compatible patch releases. 2.1.0 and 2.1.1 preserves the same package and namespace boundary while adding backward-compatible public/API and adoption-surface expansion.
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 for the stable 2.x line
Starting with 2.0.0, packages identified as stable are expected to preserve their documented public API surface for consumers within the same major version.
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.
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, audit residue, 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.
Current 2.x stable family
2.1.1 is the current stable minor release. It preserves the 2.0.0 public package and namespace boundary after the public rename from CDCavell.AsiBackbone.* to AsiBackbone.*.
| Package | 2.x stable role |
|---|---|
AsiBackbone.Core |
Framework-neutral governance primitives and durable artifact contracts for the current 2.x line, including optional policy evaluator fast-abort configuration and builder-style audit residue 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, and outbox records. |
AsiBackbone.AspNetCore |
ASP.NET Core host adapters, endpoint governance, development diagnostics, endpoint fast-abort metadata, 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. |
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, 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.
Assembly version policy
For the stable 2.x package line, AsiBackbone keeps AssemblyVersion fixed at 2.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+... |
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 2.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;
- 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
AssemblyVersionstrategy 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.