Release Flow
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.
Preparing a release
Section titled “Preparing a release”- Choose an unused version and update
package.json. - Use conventional commit subjects for noteworthy changes:
feat:for featuresfix:for bug fixesperf:,refactor:, orrevert:for other noteworthy changes
- 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.”
Running the release pipeline
Section titled “Running the release pipeline”The pipeline is driven by the Purview.Build tool through just:
just pipeline-release # restore, build, lint, tests, pack, publish, GitHub releasejust pipeline-local-release # Same but to a local NuGet feed (use forward slashes in paths)CI release workflow
Section titled “CI release workflow”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:
- Evaluates release eligibility with the shared tool (
purview-build release-explain --format=json). Whenv<version>already exists the job finishes green and nothing is published; a policy violation fails the job, naming theREL0nnrule that rejected it. - Builds the solution and runs the tests selected by
Build:TestFilterinpurview-build.json. - Packs the NuGet package using the exact manual version.
- Publishes the package to nuget.org, with
--skip-duplicateso a re-run after a partial failure is safe. - 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.
Analyzer release tracking
Section titled “Analyzer release tracking”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.
During a release
Section titled “During a release”- Add any new, changed, or removed diagnostics to
AnalyzerReleases.Unshipped.mdas they are introduced. - When the release is cut, move every row from
AnalyzerReleases.Unshipped.mdinto a new## Release <version>section inAnalyzerReleases.Shipped.mdand leave the unshipped file empty again. - 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:
dotnet build src/src/SourceGenerators/SourceGenerators.csproj -c ReleaseThe build must produce no RS2000–RS2008 diagnostics.
Public API baseline
Section titled “Public API baseline”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.
- A new public symbol is added to
PublicAPI.Unshipped.txtas 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 theRS0016text from the compiler output into the file. - When the release is cut, move every row from
PublicAPI.Unshipped.txtintoPublicAPI.Shipped.txtand leave the unshipped file with just its#nullable enableheader. - 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.
Pack validation
Section titled “Pack validation”.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.