Release flow
This repository uses the shared Purview.Build pipeline for both
PR validation and releases. Consuming repositories own configuration (through purview-build.json) but
not pipeline source code.
.github/workflows/pr.yml— PR validation.github/workflows/release.yml— release on push tomainpurview-build.json— pipeline configuration
PR validation
Section titled “PR validation”pr.yml runs on pull requests targeting main and delegates to the shared purview-build.yml
workflow. It runs:
dotnet restoreofsrc/ResourceKit.slnxdotnet build --no-restore --configuration Release- CSharpier lint across the repository
- The full test suite — every project discovered under
src/testsmatching*Tests.csproj, including the AppHost integration tests, with the/*/*/*/*TUnit tree-node filter dotnet packand package-content validation
The release pipeline runs the same test step against the same purview-build.json, so a suite the PR
passes is the suite the release runs. src/tests/Repository.UnitTests/PipelineTests.cs fails if either
workflow narrows the filter or disables tests.
The integration tests start the example AppHosts (and their Docker containers), so the test step runs
one test project at a time (Build:MaxTestParallelism) and the AppHost fixtures inside a project start
serially. The two target-framework test apps still run in parallel, but each is given its own Aspire
target-port range so Aspire cannot allocate the same port to both.
The PR workflow does not tag, release, or publish packages.
Versioning model
Section titled “Versioning model”package.json is the authoritative release version source. The release workflow reads:
bun -p "require('./package.json').version"This flow assumes version prep already happened before release (for example with @changesets/cli
versioning and changelog updates merged to main). The release pipeline does not invent or auto-bump
versions.
Release on push to main
Section titled “Release on push to main”release.yml triggers on push to main and delegates to the shared purview-release.yml workflow
with release-mode: NuGet.
The shared workflow:
- Asks the shared tool to evaluate release eligibility (
purview-build release-explain --format=json), which resolvespackage.jsonversionand thev<version>tag. - Skips the entire release when
v<version>already exists — the job finishes green and publishes nothing — so re-merging tomain, or mergingmaininto areleasebranch, releases exactly once. A policy violation instead fails the job, naming theREL0nnrule that rejected it. - Restores, builds, lints, runs the full test suite (unit and AppHost integration), packs, and validates packages.
- Pushes every
.nupkgto nuget.org (--skip-duplicate). - Creates the
v<version>GitHub release with notes generated by GitHub. Package artifacts are not attached unless the caller passesupload-artifacts: true, which this repository does not — download released packages from nuget.org.
A release is therefore produced simply by bumping package.json (via changesets) and merging to
main. Do not create release tags manually.
Prerelease support
Section titled “Prerelease support”Prerelease versions (any SemVer containing a hyphen, for example 1.0.0-prerelease.28) release
through the same push-to-main flow. The v<version> tag and GitHub release are still created and
packages published.
The shared pipeline does mark the GitHub release as a prerelease: Release:MarkPrerelease
defaults to true, so a version containing a hyphen is created with GitHub’s prerelease flag set and
is therefore not presented as the repository’s latest release. This affects GitHub release metadata
only — the package is still published to nuget.org exactly as a stable version would be. Set
Release:MarkPrerelease to false in purview-build.json to publish prerelease versions as stable
GitHub releases.
Stable release preparation
Section titled “Stable release preparation”A stable release (for example 1.0.0) follows the same push-to-main flow, but requires version
preparation before the merge:
- Set
package.jsonversionto the stable version (for example1.0.0). - Align the build SDK in
global.jsonand the centrally-managed package versions inDirectory.Packages.propswith their stable releases. - Move every entry from
src/src/SourceGeneration/AnalyzerReleases.Unshipped.mdintosrc/src/SourceGeneration/AnalyzerReleases.Shipped.mdunder the released version, and leave the unshipped file empty (see below). - Add the release to
CHANGELOG.mdand update the release notes page. - Validate locally (
just lint-checkandjust pipeline-pack-validate) before merging tomain.
The GitHub release is created with automatically generated notes, grouped by the categories in
.github/release.yml.
Analyzer release tracking
Section titled “Analyzer release tracking”src/src/SourceGeneration ships public diagnostics (SG0001–SG0020), so it maintains the Roslyn
release tracking files:
AnalyzerReleases.Shipped.md— rules that have shipped in a released version.AnalyzerReleases.Unshipped.md— rules added or changed since the last release.
Microsoft.CodeAnalysis.Analyzers automatically adds these files as analyzer additional files when
they exist in the project directory, so they are validated during the build (Roslyn components build
with TreatWarningsAsErrors). Add new rules to the unshipped file while developing, and move them
into the shipped file as part of a release. See Contributing for the day-to-day
workflow.
Build-time dependencies
Section titled “Build-time dependencies”Some centrally-managed packages are build/analysis-time only (consumed with PrivateAssets), for
example Purview.Telemetry.SourceGenerator, which Purview.BuildSdk injects into every non-test C#
project, and Purview.SourceGeneratorFramework. They never flow to consumers of the NuGet package,
but the repository cannot restore unless the pinned version exists on a configured feed. A stable
release therefore requires the pinned versions to be resolvable before merging to main.
NuGet publishing
Section titled “NuGet publishing”NuGet publishing uses the shared workflow’s API-key path with the organization NUGET__APIKEY secret
(available through secrets: inherit). The pipeline also accepts NUGET_APIKEY. No long-lived
repository-level API key secrets are required.
To use NuGet Trusted Publishing (OIDC) instead, the consuming repository would need to mint the
federated credential before the shared pipeline runs; the shared workflow itself does not perform the
NuGet/login step.
Shared pipeline configuration
Section titled “Shared pipeline configuration”purview-build.json at the repository root drives the pipeline:
| Key | Value | Purpose |
|---|---|---|
Build:Solution |
src/ResourceKit.slnx |
Solution passed to restore/build/pack |
Build:TestRoot |
src/tests |
Test project discovery root |
Build:TestPatterns |
*Tests.csproj |
Test projects discovered for the test step |
Build:TestFilter |
/*/*/*/* |
TUnit tree-node filter — every test, unit and integration |
Build:MaxTestParallelism |
1 |
One test project at a time; the Aspire integration suite must not compete with the Roslyn suites for a CI runner |
PackValidation:RequireSymbolPackage |
true |
Every .nupkg needs a matching .snupkg |
PackValidation:RequireSymbolFiles |
true |
Every .snupkg must contain PDBs |
PackValidation:RequiredContent |
Expected package contents | Asserts the package ships its expected output — the lib/net10.0 and lib/net11.0 runtime assemblies + XML docs, the generator and code-fix assemblies under analyzers/dotnet/cs, buildTransitive/Purview.Aspire.ResourceKit.props, README.md, and purview-logo-light.png. It also fails on undeclared package content, so a new asset has to be added here in the same change that introduces it |
Release:Mode |
None |
Publishing is enabled only by the release workflow |
Configuration precedence is command line, environment variables, purview-build.json, then the tool’s
built-in defaults. Nested environment keys use __, for example Release__Mode=NuGet.