Versioning & API Compatibility

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

Version Scheme

Increment	Meaning
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.

Early access

Tayra is in early access. Until the 1.0-equivalent stability commitment, breaking changes can land in a minor release without going through the deprecation window above, and some already have (see the changelog). The window is the intent, not yet a guarantee. What is guaranteed even in early access is that an upgrade will never make already-encrypted data undecryptable: compatibility readers for old ciphertext formats are kept indefinitely, whatever happens to the writers.

Currently Deprecated

Symbol	Package	Use instead	Removed in
UseTayraMiddleware()	Tayra.Wolverine5 / Tayra.Wolverine6	UseTayra() - Tayra now encrypts at the serializer, not via middleware	A future release
UseAwsKeyStore()	Tayra.KeyStore.AwsParameterStore	UseAwsParameterStoreKeyStore()	A future release
[SerializedPersonalData] attribute	Tayra.Core	[PersonalData] - it now dispatches on member type; a non-string member serializes into its companion byte[]? automatically	A future release
EntityTypeBuilder.SerializedPersonalData(...)	Tayra.Core	PersonalData(...) - one generic method binds any member type	A future release
PersonalDataBuilder.WithMaskValue(string)	Tayra.Core	WithReplacement(TProp) - strongly typed to the member	A future release
[PersonalData].MaskValue property	Tayra.Core	ReplacementValue property	A future release

Removed

Symbol	Package	Removed in	Notes
BinaryFieldSerializer.Serialize()	Tayra.Core	2.4.0	Non-string [PersonalData] payloads are now UTF-8 JSON (v4). BinaryFieldSerializer.Deserialize() is deliberately kept and is not deprecated - it is the only thing that can read v3 ciphertext written by 2.3.x, so removing it would render existing PII undecryptable. Writing v3 ended; reading v3 has not.
Analyzer TAYRA012	Tayra.Core	2.4.0	[PersonalData] on a non-string member is now valid (it serializes into a companion byte[]?), so the rule no longer applies. The companion-required guard moved to TAYRA013.
SerializedPersonalDataBuilder<T>	Tayra.Core	2.4.0	Folded into the generic PersonalDataBuilder<T, TProp>; its WithGroup, StoredIn, and WithReplacement are now on the unified builder.

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.