Release Flow
Releases are driven by the shared purview-dev/build pipeline through the
GitHub Actions workflows in .github/workflows/. Consuming repositories own configuration through
.config/purview-build.json, not pipeline source code.
Versioning
Section titled “Versioning”package.json is the authoritative release and package version; every package is versioned from it by
Purview.BuildSdk. Never diverge a project’s version by hand. Read the current line from package.json
(just version) rather than from this page; a prerelease uses a MAJOR.MINOR.PATCH-prerelease.N suffix.
Releasing a version
Section titled “Releasing a version”A push to main publishes, so everything below has to be true before the merge.
- Rename the changelog heading to the version being released.
CHANGELOG.md’s newest## <version>heading is the one that ships; there is noUnreleasedheading, precisely so a merge cannot publish an unnamed release. Anything a consumer has to act on goes under that version’s### Upgrade notes, each note naming the old form, the new form and the edit to make. - Move new diagnostics into a shipped block, as Analyzer release tracking describes. A rule stays recorded under the release that introduced it, so earlier blocks are never rewritten.
- Bump the package-validation baseline.
src/Directory.Build.targetssetsPackageValidationBaselineVersionto the previous stable release; it must name the version currently on NuGet, not the one being released. The build then failsdotnet packon an unintended public-API change. An intended one needs aCompatibilitySuppressions.xmlbeside the owning project (dotnet pack /p:GenerateCompatibilitySuppressionFile=true) and a matching upgrade note — the two are each other’s evidence. - Run
just pipeline-pack-validate, which covers restore, build, lint, tests, pack and pack validation in one pass (just pipeline-prstops after the tests), andjust smoke-packed-consumerswhen the generator, packaging or a dependency version changed.
Workflows
Section titled “Workflows”| Workflow | Trigger | Pipeline |
|---|---|---|
.github/workflows/pr.yml |
pull requests against main (opened, synchronize, reopened, ready_for_review) |
build: shared purview-build.yml, with the [Category=Unit] test filter, run-pack: true and validate-pack: true; packed-consumers: packs to an isolated feed, publishes and runs the Native AOT, Blazor WebAssembly and Blazor Server consumers, leak-scans their output and proves every ForbiddenContent rule rejects a package |
.github/workflows/release.yml |
push to main |
shared purview-release action with release-mode: NuGet |
Both workflows take the SDK from global.json through purview-dev/build’s dotnet-sdk action and
purview-release action; neither repeats the version. The packed-consumers job adds a second
actions/setup-dotnet step for the .NET 10 runtime the net10.0 consumer runs on. setup-dotnet’s
global-json-file input is not used, because it resolves rollForward: latestMajor as the LTS channel and
leaves the job without the pinned SDK. Read the pinned version from global.json rather than from this page.
The release workflow packs, publishes to NuGet, and creates the v<version> GitHub release only when that tag does
not already exist. Do not create release tags or publish packages manually.
.config/purview-build.json
Section titled “.config/purview-build.json”| Key | Value |
|---|---|
Build:Solution |
src/Results.slnx |
Build:TestRoot |
src/tests |
Build:TestPatterns |
*Tests.csproj |
Build:TestProjects |
*Tests* |
Build:TestFilter |
/*/*/*/* (the PR workflow narrows it to [Category=Unit] through its test-filter input) |
PackValidation:RequiredCompilerFlags |
optimization=release, asserted for every assembly that ships a PDB |
PackValidation:RequireSymbolPackage |
false |
PackValidation:RequiredContent |
The exhaustive per-package content declaration |
PackValidation:ForbiddenContent |
Paths no package may ship (*): compiler-host assemblies anywhere, and the generator outside analyzers/ |
Release:Mode |
None (publishing is enabled only by the release workflow) |
RequireExplicitContent defaults to true, so RequiredContent is exhaustive: a package with no rule, or an
entry matching none of its globs, fails validation. Update it whenever package content changes — a new asset, a
removed PDB, a renamed analyzer.
Packed shapes that must not regress
Section titled “Packed shapes that must not regress”Purview.Resultsships the runtime library aslib/<tfm>/Purview.Results.dllplus its XML documentation, and the merged source generator underanalyzers/dotnet/cs/only — never underlib/— with no analyzer PDB, because the packaged analyzer is the framework’s ILRepack-merged assembly whose rewritten PDB carries no Roslyn compiler-flags record. TheCS0029code fix ships beside it asPurview.Results.SourceGenerator.CodeFixes.dlland is never IL-merged into the generator. The generator is not published as a separate package.- The library packages ship
lib/<tfm>/<assembly>.dllplus the XML documentation file, and a symbol package. - Every package ships its
README.mdandpurview-logo-light.png. Agent skills are not packed —Purview.BuildSdk1.0.6 removed skill packaging, and they are delivered from the repository-rootskills/folder by the skills CLI instead.
The framework assembly must never appear loose beside the merged analyzer — ForbiddenContent rejects
analyzers/**/Purview.SourceGeneratorFramework.dll.
Analyzer release tracking
Section titled “Analyzer release tracking”The generator bundled in Purview.Results ships public diagnostics (RSG1000–RSG1009 and RSG9000), so it
maintains the Roslyn release-tracking files. New or changed rules go in
src/src/SourceGenerator/AnalyzerReleases.Unshipped.md, which the compiler’s RS2008 catalogue validates during
the build, and move into a ## Release <version> block in AnalyzerReleases.Shipped.md when that version ships.
RSG2000 is a suppression id, not a reported rule, so it must not appear in either file.
Commands
Section titled “Commands”just pipeline-pr # restore, build, lint, testsjust pipeline-build # restore, build, lint (no tests, no release)just pipeline-pack-validate # restore, build, lint, tests, pack, validate contentsjust pipeline-release # pack, publish, GitHub release (NuGet mode)just pipeline-local-release # pack, publish to a local NuGet feedjust version # the version package.json declarespipeline-pr and the other pipeline recipes run dotnet tool restore, which installs the pinned
Purview.Build from .config/dotnet-tools.json.
Testing the packed packages locally
Section titled “Testing the packed packages locally”A .nupkg published under a new version always extracts fresh, so the supported flow is: bump
package.json, publish to the local feed, then scrub the consuming repository.
In this repository, publish the new version to the local feed:
just pipeline-local-release --PublishLocalNuGet:LocalFeedPath=p:/_sync-projects/.local-nuget/Then, in the consuming repository:
just scrubjust buildLOCAL_NUGET_FEED_PATH is exported in the development environment, so the explicit switch is only needed when it
is not. NuGet reuses an already-extracted package for the same id and version, so republishing the same
version requires deleting $(NUGET_PACKAGES)/<package-id>/<version> first — prefer a new version.
Related
Section titled “Related”- Contributing — the local commands and quality gates.
- Diagnostics — the rules the release-tracking file lists.