Skip to content
Purview Dev logo

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 to main
  • purview-build.json — pipeline configuration

pr.yml runs on pull requests targeting main and delegates to the shared purview-build.yml workflow. It runs:

  1. dotnet restore of src/ResourceKit.slnx
  2. dotnet build --no-restore --configuration Release
  3. CSharpier lint across the repository
  4. The full test suite — every project discovered under src/tests matching *Tests.csproj, including the AppHost integration tests, with the /*/*/*/* TUnit tree-node filter
  5. dotnet pack and 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.

package.json is the authoritative release version source. The release workflow reads:

Terminal window
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.yml triggers on push to main and delegates to the shared purview-release.yml workflow with release-mode: NuGet.

The shared workflow:

  1. Asks the shared tool to evaluate release eligibility (purview-build release-explain --format=json), which resolves package.json version and the v<version> tag.
  2. Skips the entire release when v<version> already exists — the job finishes green and publishes nothing — so re-merging to main, or merging main into a release branch, releases exactly once. A policy violation instead fails the job, naming the REL0nn rule that rejected it.
  3. Restores, builds, lints, runs the full test suite (unit and AppHost integration), packs, and validates packages.
  4. Pushes every .nupkg to nuget.org (--skip-duplicate).
  5. Creates the v<version> GitHub release with notes generated by GitHub. Package artifacts are not attached unless the caller passes upload-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 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.

A stable release (for example 1.0.0) follows the same push-to-main flow, but requires version preparation before the merge:

  1. Set package.json version to the stable version (for example 1.0.0).
  2. Align the build SDK in global.json and the centrally-managed package versions in Directory.Packages.props with their stable releases.
  3. Move every entry from src/src/SourceGeneration/AnalyzerReleases.Unshipped.md into src/src/SourceGeneration/AnalyzerReleases.Shipped.md under the released version, and leave the unshipped file empty (see below).
  4. Add the release to CHANGELOG.md and update the release notes page.
  5. Validate locally (just lint-check and just pipeline-pack-validate) before merging to main.

The GitHub release is created with automatically generated notes, grouped by the categories in .github/release.yml.

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.

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 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.

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.