Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .config/purview-build.json
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,7 @@
},
"Release": {
"Eligibility": {
"Policy": "TrunkReservesMinor"
"Policy": "ReleaseOnMain"
}
}
}
3 changes: 2 additions & 1 deletion .github/workflows/pr.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,8 @@ on:
# re-evaluate the required build gate once it is marked ready for review.
types: [opened, synchronize, reopened, ready_for_review]
# Every merge to main is built and tested too, so main's own status reflects what was merged rather
# than the last PR head. This never publishes: releases still come only from release/** (release.yml).
# than the last PR head. This job never publishes: release.yml, which also runs on every push to main,
# is what publishes a bumped package.json version.
push:
branches: [main]

Expand Down
10 changes: 8 additions & 2 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -1,8 +1,12 @@
name: Release

# A merge to main releases. The release tool decides per push (`release-explain`, policy ReleaseOnMain in
# .config/purview-build.json): a package.json version with no `v<version>` tag yet is published to
# nuget.org and tagged with a GitHub release; a version that is already released is skipped and the job
# finishes green, so a merge that does not bump the version publishes nothing. Bump package.json to ship.
on:
push:
branches: ["release/**"]
branches: [main]
workflow_dispatch:

permissions:
Expand All @@ -15,7 +19,9 @@ permissions:

concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
# Never cancel a release in flight: a run cancelled between publishing to nuget.org and tagging would
# leave a published version with no tag or GitHub release. Later merges queue behind it instead.
cancel-in-progress: false

jobs:
release:
Expand Down
17 changes: 9 additions & 8 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -285,14 +285,15 @@ Commit messages follow Conventional Commits enforced by the `commit-msg` lefthoo
- `package.json` is the authoritative release and package version. Do not diverge project versions by hand.
- `.github/workflows/pr.yml` builds and tests pull requests **and every push to `main`** through the
shared `purview-dev/build/.github/workflows/purview-build.yml`, with pack and validation enabled (plus
the Docker and WSLC contract jobs). A push to `main` never publishes; superseded PR runs are
cancelled, `main` runs are not.
- `.github/workflows/release.yml` runs the shared release pipeline with `release-mode: NuGet` on a push to a
`release/**` branch (or a manual dispatch), **not** on a push to `main`. Cut a release by merging the
version bump into `main`, then pushing a `release/v…` branch named after the version from it (for
example `release/v1.0.9` for `1.0.0-prerelease.9`). `.config/purview-build.json`
sets the `TrunkReservesMinor` eligibility policy; a version whose `v<version>` tag already exists is
skipped (`REL002`), so every release needs a new `package.json` version. See
the Docker and WSLC contract jobs); superseded PR runs are cancelled, `main` runs are not.
- `.github/workflows/release.yml` runs the shared release action with `release-mode: NuGet` on **every
push to `main`** (or a manual dispatch): merging a `package.json` version bump into `main` publishes it.
`.config/purview-build.json` sets the `ReleaseOnMain` eligibility policy; a version whose
`v<version>` tag already exists is skipped (`REL002`), so a merge without a bump publishes nothing and
every release needs a new `package.json` version. Release runs are never cancelled in flight
(`cancel-in-progress: false`): a run cancelled between publishing and tagging would leave a published
version with no tag. The nuget.org Trusted Publishing policy is registered against the file name
`release.yml`, so keep the file name. See
[Release Flow](docs/wiki/contributing/Release-Flow.md).
- `.github/workflows/integration-wsl.yml` runs the WSLC integration suites. The fast contract suite runs on
a hosted `windows-2025` runner on every pull request from `pr.yml`; the full service-module matrix runs
Expand Down
36 changes: 15 additions & 21 deletions docs/wiki/contributing/Release-Flow.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,45 +50,39 @@ the run with the failing module's output.

- `.github/workflows/pr.yml` — pull requests **and every push to `main`** build and test via the shared
`purview-dev/build/.github/workflows/purview-build.yml`, with pack and validation enabled, plus the
Docker and WSLC contract jobs. A push to `main` builds only; it never publishes.
- `.github/workflows/release.yml` — a push to a **`release/**` branch** (or a manual `workflow_dispatch`)
calls `purview-dev/build/.github/workflows/purview-release.yml` with `release-mode: NuGet`. It evaluates
release eligibility and, when eligible, builds, tests, packs, publishes to NuGet and creates the
`v<version>` tag and GitHub release. A push to `main` does **not** release.
Docker and WSLC contract jobs.
- `.github/workflows/release.yml` — **every push to `main`** (or a manual `workflow_dispatch`) runs the
shared `purview-dev/build/actions/purview-release` action with `release-mode: NuGet`. It evaluates
release eligibility and, when the verdict is `Release`, builds, tests, packs, publishes to NuGet and
creates the `v<version>` tag and GitHub release. A merge that does not change the `package.json` version
is skipped and publishes nothing. Release runs are never cancelled mid-flight; a later merge queues.

Both workflows pin `dotnet-version` to the SDK in `global.json`; keep them in sync when the SDK is bumped,
and keep `purview-build.json` pointing at `src/Containers.slnx`.

## Cutting a release

1. Bump `version` in `package.json` on a branch (keep the `-prerelease.N` suffix), and merge it into
`main` through a pull request.
2. Push a release branch named after the version from `main`. The convention is `release/v<major>.<minor>.<N>`,
where `N` is the prerelease number, for example `release/v1.0.9` for `1.0.0-prerelease.9`:
1. Bump `version` in `package.json` on a branch (keep the `-prerelease.N` suffix until 1.0.0), and merge
it into `main` through a pull request.
2. The Release workflow runs on that merge and publishes the new version. Nothing else is needed: no
release branch and no manual tag.

```bash
git switch main && git pull
git push origin main:refs/heads/release/v1.0.9
```

3. The Release workflow runs on that push. Each release is a new `package.json` version and a new
release branch.
Every release is a new `package.json` version. A merge without a version bump runs the Release workflow
too, which skips (`REL002`: the tag already exists) and finishes green.

Check the decision locally before pushing with `dotnet tool run purview-build -- release-explain`. It runs
nothing and publishes nothing; it reports the verdict and the rule that decided it.

### Eligibility

`.config/purview-build.json` selects the **`TrunkReservesMinor`** policy: `main` is the trunk, and
`release/*` branches are the stable and servicing refs that publish. The tool evaluates these rules:
`.config/purview-build.json` selects the **`ReleaseOnMain`** policy (the tool's default): `main` is the
ref that publishes, for prereleases and stable versions alike. The tool evaluates these rules:

| Rule | Checks |
| --- | --- |
| `REL001` | The version is valid for NuGet. |
| `REL002` | No `v<version>` tag exists yet. A version that has already been released is **skipped**, so every release needs a new `package.json` version. |
| `REL003` | Constrains stable (non-prerelease) versions; prereleases pass. |
| `REL004` | Constrains versions with a non-zero PATCH component. |
| `REL005` | The version is consistent with what already exists on its `<major>.<minor>` line. |
| `REL003` | A stable (non-prerelease) version is released only from `main`; prereleases pass. |

The workflow fails on a `Fail` verdict, logs a notice and publishes nothing on `Skip`, and publishes only
on `Release`.
Expand Down
Loading