diff --git a/.config/purview-build.json b/.config/purview-build.json index a1ed7c0..d9525fa 100644 --- a/.config/purview-build.json +++ b/.config/purview-build.json @@ -143,7 +143,7 @@ }, "Release": { "Eligibility": { - "Policy": "TrunkReservesMinor" + "Policy": "ReleaseOnMain" } } } \ No newline at end of file diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml index 758dd3b..8fa5704 100644 --- a/.github/workflows/pr.yml +++ b/.github/workflows/pr.yml @@ -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] diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 6ab891f..1836ebc 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -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` 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: @@ -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: diff --git a/AGENTS.md b/AGENTS.md index f6c5257..ed5d5fe 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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` 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` 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 diff --git a/docs/wiki/contributing/Release-Flow.md b/docs/wiki/contributing/Release-Flow.md index 5099d62..7104b6f 100644 --- a/docs/wiki/contributing/Release-Flow.md +++ b/docs/wiki/contributing/Release-Flow.md @@ -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` 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` 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..`, - 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` 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 `.` 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`.