Skip to content
Purview Dev logo

The version in package.json is maintained manually and is the sole version source used by the release pipeline. Versions must use valid SemVer, including an optional prerelease suffix when required.

  1. Choose an unused version and update package.json.
  2. Use conventional commit subjects for noteworthy changes:
    • feat: for features
    • fix: for bug fixes
    • perf:, refactor:, or revert: for other noteworthy changes
  3. Commit the version update and merge or push it to main.

Commits beginning with chore:, build:, ci:, test:, docs:, or style: are intentionally omitted from release notes. When no noteworthy commits exist, the release notes contain “Improvements ongoing.”

The pipeline is driven by the Purview.Build tool through just:

Terminal window
just pipeline-release # restore, build, lint, tests, pack, publish, GitHub release
just pipeline-local-release # Same but to a local NuGet feed (use forward slashes in paths)

A push to main triggers .github/workflows/release.yml, which calls the purview-dev/build/actions/purview-release composite action with release-mode: NuGet. It uses the action rather than the reusable purview-release.yml because nuget.org Trusted Publishing matches the OIDC job_workflow_ref claim against the caller’s own workflow file. It:

  1. Evaluates release eligibility with the shared tool (purview-build release-explain --format=json). When v<version> already exists the job finishes green and nothing is published; a policy violation fails the job, naming the REL0nn rule that rejected it.
  2. Builds the solution and runs the tests selected by Build:TestFilter in purview-build.json.
  3. Packs the NuGet package using the exact manual version.
  4. Publishes the package to nuget.org, with --skip-duplicate so a re-run after a partial failure is safe.
  5. Creates the v<version> tag and a GitHub Release with notes generated by GitHub.

release-mode: NuGet does publish to NuGet: the shared pipeline’s PublishNuGetModule pushes every .nupkg in the artifacts folder to NuGet:FeedUrl, which defaults to nuget.org. No manual push step is required.

Two details worth knowing, because they differ from what this page previously claimed:

  • Release notes are generated by GitHub from the commit range, not assembled by the pipeline. The conventional-commit conventions above shape how those notes read, but the pipeline does no filtering of its own.
  • Packages are not attached to the GitHub Release unless the caller passes upload-artifacts: true, which this repository does not. Download released packages from nuget.org.

The source generator ships Roslyn diagnostics (ASPIREC4001–ASPIREC4007). Their release history is tracked with the standard Microsoft.CodeAnalysis.Analyzers release-tracking files:

  • src/src/SourceGenerators/AnalyzerReleases.Shipped.md — rules that have already shipped, grouped under a ## Release <version> heading.
  • src/src/SourceGenerators/AnalyzerReleases.Unshipped.md — rules added, changed, or removed since the last release. This file starts empty at the beginning of every release.

Use these exact file names, at the SourceGenerators project root. Microsoft.CodeAnalysis.Analyzers only auto-includes files called AnalyzerReleases.Shipped.md / AnalyzerReleases.Unshipped.md as compiler AdditionalFiles; any other name (for example Analysis.Shipped.md) is silently ignored and no tracking occurs.

  1. Add any new, changed, or removed diagnostics to AnalyzerReleases.Unshipped.md as they are introduced.
  2. When the release is cut, move every row from AnalyzerReleases.Unshipped.md into a new ## Release <version> section in AnalyzerReleases.Shipped.md and leave the unshipped file empty again.
  3. If the release adds, removes, or changes no diagnostics, do not add a shipped section — the unshipped file simply stays empty.

Only three descriptor attributes count as a “change”: category, default severity, and enabled-by-default status. Message text and descriptions can change without a tracking entry.

Build the generator project to verify the tracking files remain valid and complete:

Terminal window
dotnet build src/src/SourceGenerators/SourceGenerators.csproj -c Release

The build must produce no RS2000–RS2008 diagnostics.

AspireC4.Hosting and AspireC4.Hosting.EntityFrameworkCore carry a Microsoft.CodeAnalysis.PublicApiAnalyzers baseline beside their project files. 13.6.5 is the first stable release, so its surface is the compatibility contract: removing or changing a listed symbol fails the build with RS0017, and adding an unlisted public symbol fails it with RS0016.

  1. A new public symbol is added to PublicAPI.Unshipped.txt as part of the change that introduces it. The analyzer expects the exact format it reports; the simplest way to get it is to build once, then move the RS0016 text from the compiler output into the file.
  2. When the release is cut, move every row from PublicAPI.Unshipped.txt into PublicAPI.Shipped.txt and leave the unshipped file with just its #nullable enable header.
  3. A deliberate removal is recorded by prefixing the shipped row with *REMOVED* rather than deleting it, so the break is visible in review.

RS0026/RS0027 are suppressed in the two projects for their shipped overload shapes, which are also part of the generated TypeScript surface; the baseline still records those signatures.

.config/purview-build.json declares the package content that must be present in the packed .nupkg (PackValidation:RequiredContent). Because RequireExplicitContent is on, it is also the exhaustive list: an entry no rule matches fails validation.

The lib/... entries use the $(TFM) token, which the validator expands to one entry per target framework the package ships — lib/$(TFM)/Aspire.Hosting.AspireC4.dll requires both lib/net10.0/... and lib/net11.0/... today. The rules therefore follow Purview.BuildSdk’s target set with no edit. (Earlier Purview.Build releases also expanded the token to the framework-agnostic any group contributed by a root-level build/ folder, which made lib/$(TFM)/... unsatisfiable; that is why older history pins literal frameworks.)

The source generator has no rule of its own beyond its path: it is not a separate package. AspireC4.csproj references src/src/SourceGenerators with OutputItemType="Analyzer", so pack places Aspire.Hosting.AspireC4.SourceGenerators.dll under analyzers/dotnet/cs/ in AspireC4.Hosting, and the aspirec4.hosting rule asserts it is there.