Tayra

Appearance

Versioning & API Compatibility ​

Tayra follows Semantic Versioning 2.0 to give commercial customers confidence when upgrading.

Version Scheme ​

IncrementMeaning
Major (X.0.0)Breaking changes to the public API surface
Minor (0.X.0)New features, backward-compatible additions
Patch (0.0.X)Bug fixes, performance improvements, no API changes

Deprecation Policy ​

Tayra uses a two-minor-version deprecation window:

  1. Minor N: A symbol is marked [Obsolete("Use X instead. Will be removed in vN+2.")]
  2. Minor N+1: The obsolete symbol remains available with the compiler warning
  3. Minor N+2: The symbol is removed

This gives customers at least two minor release cycles to migrate away from deprecated APIs.

Public API Surface Tracking ​

Tayra uses Microsoft.CodeAnalysis.PublicApiAnalyzers to track the public API surface of every shipped package.

Each packable project contains two files:

  • PublicAPI.Shipped.txt - API surface included in the last release
  • PublicAPI.Unshipped.txt - New API additions not yet released

How It Works ​

  • Adding a public member without updating PublicAPI.Unshipped.txt causes a build error (RS0016)
  • Removing a shipped public member without marking it as removed causes a build error (RS0017)
  • This ensures accidental breaking changes are caught at build time, not after release

Workflow for Contributors ​

Adding a new public API:

  1. Add the new type/member in code
  2. Build - the compiler will emit RS0016 with the exact symbol string
  3. Add that symbol string to PublicAPI.Unshipped.txt

Releasing a new version:

  1. Move all entries from PublicAPI.Unshipped.txt to PublicAPI.Shipped.txt
  2. Clear PublicAPI.Unshipped.txt (keep only #nullable enable)

Removing a public API:

  1. Mark the member as [Obsolete] (see deprecation policy above)
  2. After the deprecation window, remove the code
  3. Move the symbol from PublicAPI.Shipped.txt and prefix with *REMOVED*

Stability Guarantees ​

  • Tayra.Core: Stable. Breaking changes only in major versions.
  • Integration packages (Marten, Wolverine, EF Core, ASP.NET Core): Follow their upstream framework's major version cycle.
  • Key store packages: Stable. Provider-specific options may evolve with the upstream SDK.
  • Internal APIs (classes/methods not in PublicAPI.Shipped.txt): May change without notice between any versions.