Table of Contents

API Baseline and Architecture Boundary Checks

This page documents the guardrails used to protect the stable AsiBackbone package line.

These checks protect implemented package contracts; they do not turn AsiBackbone into a compliance product, signing system, or production audit guarantee.

Purpose

The stable 5.x package line uses two complementary automated guardrails:

Guardrail Purpose Current posture
Public API drift detection Detect unreviewed additions, removals, enum-value changes, and signature/declaration changes in stable managed package assemblies. Implemented through committed DocFX-derived public API baselines validated in CI and release workflows.
Core architecture boundary checks Fail if the Core package starts depending on integration or provider concerns such as ASP.NET Core, EF Core, cloud providers, robotics packages, or AI model packages. Implemented through test coverage for stable package project files.

The API baseline gate complements Semantic Versioning review; it does not decide whether a change is compatible or assign a release version automatically.

Automated public API baseline

./scripts/Validate-PublicApiBaseline.ps1 reads the managed-reference pages generated by DocFX and compares the stable managed package surface with committed files under eng/api-baseline/.

Each baseline records:

  • the DocFX UID for each public type and member;
  • the rendered C# declaration, including return/property types and generic/interface shape;
  • enum values with their displayed numeric value.

This makes the baseline diff directly reviewable in a pull request while keeping the gate independent of implementation internals. An unreviewed public addition, removal, rename, parameter/return-type change, generic/interface declaration change, or enum-value change changes the generated baseline and fails validation.

The initial 5.x baseline was generated from the published v5.0.0 DocFX managed-reference output at commit 54ddd57a4d272e9294ee5638aef723e6d5ae66a8.

Included package assemblies

The gate covers these stable managed assemblies:

  • AsiBackbone.Analyzers.dll
  • AsiBackbone.AspNetCore.dll
  • AsiBackbone.Core.dll
  • AsiBackbone.DependencyInjection.dll
  • AsiBackbone.EntityFrameworkCore.dll
  • AsiBackbone.OpenTelemetry.dll
  • AsiBackbone.Signing.LocalDevelopment.dll
  • AsiBackbone.Signing.ManagedKey.dll
  • AsiBackbone.Storage.InMemory.dll
  • AsiBackbone.Testing.dll

AsiBackbone.Templates is intentionally excluded from the managed API baseline because it is a content-only dotnet new package and exposes no managed consumer assembly. Template compatibility remains protected by the template package smoke tests. Tests, samples, benchmarks, generated DocFX artifacts, and other non-package projects are also outside the stable package baseline.

Local validation

Generate the same DocFX managed-reference output used by CI and run the baseline validator:

dotnet tool restore
dotnet tool run docfx -- docs/docfx.json
./scripts/Validate-PublicApiBaseline.ps1

A quick negative test is to temporarily remove or change a stable public member, rebuild the DocFX site, and rerun the validator. The command must report the affected baseline entry and fail. Revert the temporary API change afterward.

Intentional-change workflow

A baseline update must be explicit and reviewable. When a public API change is intentional:

  1. classify the change under API Compatibility and SemVer;
  2. use a minor release for backward-compatible stable API additions;
  3. use a major release plus migration guidance for breaking stable API changes;
  4. build DocFX and inspect the failing baseline diff first;
  5. only after that review, regenerate the baseline with:
./scripts/Validate-PublicApiBaseline.ps1 -Update
git diff -- eng/api-baseline
  1. commit the baseline diff in the same pull request as the API change;
  2. record the intended SemVer impact in the pull request and applicable release documentation.

Running -Update is not itself approval. A baseline file must not be regenerated merely to silence CI without reviewing the consumer impact.

Implemented architecture boundary check

The Core test suite continues to include package-boundary checks that inspect stable package project files.

The checks verify that:

  • AsiBackbone.Core has no ProjectReference entries;
  • AsiBackbone.Core does not reference integration/provider package families such as ASP.NET Core, EF Core, cloud-provider packages, robotics packages, or AI model packages;
  • AsiBackbone.Storage.InMemory, AsiBackbone.EntityFrameworkCore, and AsiBackbone.AspNetCore reference Core through the expected dependency direction instead of referencing each other through integration layers.

This keeps the stable package dependency direction aligned with the documented shape:

AsiBackbone.Core
  <- AsiBackbone.Storage.InMemory
  <- AsiBackbone.EntityFrameworkCore
  <- AsiBackbone.AspNetCore

The public API baseline work does not replace or weaken these architecture checks.

CI and release enforcement

The public API baseline validation runs after DocFX generation in:

  • the normal CI workflow;
  • Stable Release Validation;
  • Publish AsiBackbone Packages before packing/publishing proceeds.

Because the baseline files live in source control, an intentional API update appears in the same pull-request diff as the implementation change. An accidental API change cannot pass by changing generated build output alone.

SemVer alignment

Public API review follows the compatibility guidance in API Compatibility and SemVer:

  • patch releases should not intentionally add or break stable public APIs;
  • minor releases may add compatible APIs, options, adapters, and behavior after baseline review;
  • major releases are reserved for breaking stable API changes;
  • preview/provider packages may follow their own stability path before being promoted.

Architecture boundary checks enforce the corresponding package rule: Core remains framework-neutral, while ASP.NET Core, EF Core, storage, gateway, signing, cloud, robotics, and provider concerns stay in their own packages or host applications.

Current decision

  • Stable managed 5.x package APIs are protected by committed, reviewable DocFX-derived baselines.
  • CI and release workflows fail on unreviewed public API drift.
  • Intentional baseline updates require explicit SemVer review and travel with the implementation change.
  • Core dependency-boundary checks remain implemented and unchanged.
Edit this page