Skip to main content

Versioning Strategy

Current Status​

Excalibur is in pre-release, targeting a first stable release of 10.0.0. APIs may change between pre-release builds. Use pre-release versions for evaluation, early adoption, and feedback.

Version Scheme​

The package major version matches the targeted .NET major version. Because Excalibur single-targets net10.0, the first stable release is 10.0.0. When the framework's development line moves to a newer runtime — for example net11.0 — that line ships as 11.x.

Version ComponentMeaningExample
Major (10.x, 11.x, …)The targeted .NET major version10.x targets net10.0; 11.x targets net11.0
Minor (10.X.0)New features, backward compatible within the majorNew middleware, new transport provider
Patch (10.0.X)Bug fixes, backward compatible within the majorFix null reference, correct calculation

Minor and patch releases follow Semantic Versioning 2.0.0 within a major line: they are always backward compatible. The major number is not an independent API-break counter — it tells you, at a glance, which .NET runtime the package targets, with zero ambiguity about framework compatibility. This mirrors how the .NET platform itself ships (Microsoft.Extensions.* and Microsoft.AspNetCore.* lock their major to the .NET major), so an Excalibur version reads like a first-party .NET package.

Each Excalibur package single-targets one .NET major. There is no multi-targeting of older runtimes, which lets the framework adopt current-runtime APIs and current third-party dependency majors without being pinned to what also resolves on an older .NET.

Release Stages​

StageNuGet TagAPI StabilityRecommended For
Alpha10.0.0-alpha.NAPIs may change between releasesEvaluation, early adoption, feedback
Beta10.0.0-beta.NAPIs are feature-complete but may have minor adjustmentsIntegration testing, pre-production validation
Release Candidate10.0.0-rc.NAPIs are frozen; only critical bug fixesFinal validation before production
Stable10.0.0Backward-compatible within the major lineProduction use

What Pre-Release Means for You​

  • You can build real applications -- the framework is functionally complete with an extensive automated test suite
  • APIs may change -- method signatures, interface shapes, and configuration patterns may evolve
  • No guaranteed upgrade path between pre-release builds -- consult release notes before upgrading
  • Feedback is welcome -- your input directly shapes the stable API surface

Breaking Change Policy​

Breaking changes are communicated through multiple channels:

  1. CHANGELOG.md -- Updated for every release with categorized changes (Added, Changed, Deprecated, Removed, Fixed)
  2. PublicAPI tracking -- PublicAPI.Shipped.txt and PublicAPI.Unshipped.txt files in each package track API surface changes
  3. GitHub Releases -- Tagged releases with detailed notes
  4. Migration guides -- For significant changes, dedicated migration documentation is provided

During Pre-Release (Alpha/Beta)​

Breaking changes may occur between any pre-release version. Always review the CHANGELOG before upgrading.

After Stable Release​

  • Within a major line (a single .NET major), minor and patch releases are always backward compatible
  • Breaking API changes are reserved for a new major line, which coincides with adopting a new .NET major
  • Behavioral changes (same API, different behavior) are treated as breaking

Deprecation Policy​

Once stable, Excalibur follows a minimum deprecation window:

  1. Deprecation notice -- The API is marked with [Obsolete("Use X instead.")] and documented in the CHANGELOG
  2. Minimum one minor version -- The deprecated API continues to work for at least one minor release cycle within the current major line
  3. Removal -- The API is removed at the next major line, with a migration guide

During pre-release, deprecated APIs may be removed in any subsequent build.

Upgrade Best Practices​

  1. Read the CHANGELOG -- Check for breaking changes and migration notes before upgrading
  2. Test before upgrading -- Run your full test suite on the current version
  3. Upgrade in staging first -- Validate in a non-production environment
  4. Back up persistence stores -- Event stores, outbox tables, and saga stores before major upgrades
  5. Plan rollback -- Always have a rollback strategy for production deployments

Subscribing to Updates​

Stay informed about releases and changes:

  • GitHub Releases -- Watch the Excalibur repository for release notifications
  • CHANGELOG -- Review CHANGELOG.md in the repository root for detailed change history
  • NuGet -- Configure NuGet notifications for Excalibur.Dispatch and other packages you depend on

See Also​