BlueTusk
GitHubGet Started
Operations · docs/api-compatibility.md

API compatibility

Public API baselines and compatibility expectations.

3 min read624 wordsSource synchronized
View source on GitHub
ON THIS PAGE

API compatibility

BlueTusk protects every publishable Provider-family library with compiler-enforced public API contracts. This includes the wire stack, ADO.NET, replication, EF Core and design tooling, optional PostgreSQL extensions, and cloud identity adapters. The analyzer is a private build dependency; it does not become a runtime or package dependency of BlueTusk.

The public API naming policy keeps the product brand at framework/product boundaries while requiring natural domain and fluent member names inside the provider.

Baseline scope

The V1 candidate budget records 8,308 public and protected signatures across 28 Provider-family API-governed libraries, including nullable annotations and compiler-generated record members. Across all six product families, the exact machine-enforced budget is 12,991 signatures.

Surface Projects Shipped signatures Contract role
Core wire, security, type, client, ADO.NET, and DI 8 3,024 Transport through pooled ADO.NET, schema discovery, hosting, and native data paths
Replication and pgoutput 2 847 Physical/logical replication, decoding, slots, and feedback
EF Core and design tooling 2 3,890 Runtime provider, PostgreSQL features, migrations, and scaffolding
Extension SDK and testing 2 62 Immutable plug-in and compatibility seams
Optional extension packages and EF adapters 11 457 Citext, hstore, ltree, pg_trgm, pgvector, PostGIS, and TimescaleDB
Cloud identity adapters 3 12 AWS, Azure, and Google Cloud token contracts

The source generator is governed by Roslyn analyzer-release tracking. Executable tools and content-only template packages do not expose a reusable library API. The Provider package manifest names the template package project explicitly, so its embedded sample projects cannot be mistaken for release projects.

Change policy

Each covered project owns PublicAPI.Shipped.txt and PublicAPI.Unshipped.txt:

  • Shipped entries are the compatibility floor. Removing a symbol, changing its signature/accessibility, or changing its nullable contract fails a normal build.
  • Additive APIs must be reviewed and recorded in PublicAPI.Unshipped.txt while they are being finalized. At a release boundary, accepted entries move to the shipped file without changing their canonical text.
  • A source-compatible overload can still create overload-resolution or behavioral breaks. API review therefore covers ownership, disposal, cancellation, sync/async parity, defaults, exceptions, and forward-compatible PostgreSQL behavior in addition to analyzer output.
  • A shipped break is not fixed by deleting or rewriting the baseline entry. It requires an explicit versioning decision, migration guidance, release-note entry, and the applicable test/documentation changes. Security and correctness fixes follow the same review but may justify a major-version break.
  • Suppressing a public API analyzer diagnostic requires a documented rationale; there are no repository-wide compatibility suppressions.

The checked-in Provider V1 candidate freeze hashes every shipped Provider baseline. Streams, Sync, Live, Control Plane, and ContinuousGraph have matching family freezes, including the ContinuousGraph freeze. Conformance tests also require every publishable Provider library to own both baseline files and require all unshipped files to be empty at the freeze. Changing the manifest hash is a release decision, not a way to bypass API review.

Verification

The repository conditionally enables Microsoft.CodeAnalysis.PublicApiAnalyzers whenever a project contains a shipped baseline. Warnings are errors, so the ordinary commands are the gate:

dotnet restore BlueTusk.slnx
dotnet build BlueTusk.slnx -c Release --no-restore
dotnet pack BlueTusk.slnx -c Release --no-build --output artifacts/packages

After the immutable candidate is frozen, any signature or freeze-manifest change invalidates its exact-SHA evidence and requires a new candidate. Review both baseline files in every public API change. The canonical signatures are generated by the analyzer, kept in its accepted canonical order for deterministic diffs, and checked on Windows and Linux by the existing build matrix. Run the Provider freeze test with:

dotnet test tests/BlueTusk.ConformanceTests/BlueTusk.ConformanceTests.csproj `
  -c Release --filter FullyQualifiedName~ProviderApiFreezeTests