Skip to content
Purview Dev logo

Documentation section: Project

Versioning and compatibility

Purview.Aspire.ResourceKit follows Semantic Versioning (MAJOR.MINOR.PATCH). The release version is authoritative in package.json; the release pipeline tags the commit v<version> and publishes matching NuGet packages.

  • MAJOR — a breaking change to the public surface (see below).
  • MINOR — additive, backwards-compatible functionality.
  • PATCH — backwards-compatible fixes and documentation updates.

Prereleases use a hyphenated suffix (for example 1.0.0-prerelease.41) and ship through the same push-to-main pipeline. They are published so consumers can validate upcoming changes early; they carry no stability guarantee. 1.0.0 is the first stable release.

The runtime targets .NET 10 and .NET 11 and nothing lower, so a consumer needs a net10.0 or net11.0 AppHost. The package ships lib/net10.0 (the floor) and lib/net11.0 (the newest leg); there is no net8.0 or net9.0 leg to fall back to.

Raising the floor is a MAJOR version, because a consumer on an older framework cannot take the package at all. Adding a framework is additive, but the new leg does not get to raise the dependency floor: both legs declare the lowest-compatible Microsoft.Extensions.* 10.x band, because the floor a published package declares becomes the floor every consumer inherits. The net11.0 leg consumes the net10.0 assets of those packages deliberately. PackageToolchainTests fails the build if a Microsoft.Extensions.* reference drifts into the 11.x band.

The Roslyn components (SourceGeneration, SourceGeneration.CodeFixes) target netstandard2.0 regardless: a generator runs inside the compiler and IDE host, where the consumer’s target framework is irrelevant.

Once a version is stable, the following are treated as public contracts:

  • The attributes [HostKit], [ResourceDefinition], and [ResourceDefinition<TResource>], including their named arguments (Name, PropertyName, ExtensionMethodName, GenerateOptions, Mode, Parent, ProjectPath).
  • The runtime types and members consumed by AppHost code (HostKitBase, ResourceKitBase, ResourceKitMode, OptionsHelper, and the IResourceBuilder/WithEnvironment extensions).
  • The names and shapes of generated members (BuildResource, ConfigureResource, IsResourceEnabled, Mode, generated host properties, generated options types, and the generated Add<HostKit>() extension method).
  • The diagnostic IDs SG0001–SG0020, their meanings, and their severities.

Renaming or removing any of these requires a MAJOR version and a documented migration path.

  • The exact text of generated code and diagnostic messages.
  • Build-time-only dependencies consumed through PrivateAssets (they never flow to consumers).

Diagnostic IDs are stable identifiers. New rules are introduced in the unshipped analyzer release tracking file and only become part of a released version when they move into the shipped file as part of a release. See Contributing and Release flow for the release-time procedure.