diff --git a/AGENTS.md b/AGENTS.md index f80a06cc3..ca7668e06 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,7 +13,7 @@ Originally NUKE by [matkoch](https://github.com/matkoch); under new maintenance **Rebrand status:** the structural rename has landed — namespaces (`Fallout.*`), package IDs, project filenames, and the global tool name (`dotnet fallout`) are all in place. Legacy `Nuke.*` lives on only as the consumer transition shims under `src/Shims/`. See [docs/rebrand-plan.md](docs/rebrand-plan.md) for the locked namespace mapping. **Versioning & channels (calendar versioning, dual-pace — [ADR-0004](docs/adr/0004-calendar-versioning-and-dual-pace-channels.md)).** The project ships on **calendar versions `YYYY.MINOR.PATCH`** (mechanically valid semver; major = year). Two paces run in parallel: -- **`main` = the edge channel** — fast/AI-assisted, intentionally unstable, daily date-stamped prereleases (`2026.2.0-edge..`) to **GitHub Packages only**. Light/fast review. +- **`main` = the edge channel** — fast/AI-assisted, intentionally unstable, per-commit prereleases (`2026.1.0-edge..g`, NB.GV-native) to **GitHub Packages only**. Light/fast review. - **`release/YYYY` = the stable train** — hardened deliberately, non-breaking minors/patches only after the cut, rigorous review. Stable tags publish to nuget.org (opt-in) + GitHub Packages + GitHub Releases. - **Breaking changes are batched to the yearly major cut** — they accumulate on `main` and ship as next year's `YYYY+1.0.0`. Mid-year stable is strictly non-breaking. - **Legacy `release/v10`** (+ `hotfix/v10.x`) stays on semver `10.x`, security/critical fixes only. **`release/v11` is retired** (nothing clean shipped; its work re-homed onto the 2026 line). diff --git a/docs/adr/0004-calendar-versioning-and-dual-pace-channels.md b/docs/adr/0004-calendar-versioning-and-dual-pace-channels.md index ac2e086f6..edc4154b6 100644 --- a/docs/adr/0004-calendar-versioning-and-dual-pace-channels.md +++ b/docs/adr/0004-calendar-versioning-and-dual-pace-channels.md @@ -40,11 +40,12 @@ This replaces the old "any breaking change bumps the major in the same PR, any t `main` stops being publish-silent and becomes the **edge** channel. -- Every push to `main` (or a daily build) produces a date-stamped prerelease: `YYYY.MINOR.PATCH-edge..`. The **core targets the *next* planned version** (e.g. if `2026.1.0` is the current stable, edge builds `2026.2.0-edge.…`), so edge prereleases sort *above* current stable and consumers actually resolve them. +- Every push to `main` produces an `-edge` prerelease whose identifier lives in the prerelease segment (not the version core). The **core targets the *next* planned version**, so edge prereleases sort *above* the current stable line and consumers actually resolve them. + > **Implementation note (2026-05-30):** as built, `main`'s `version.json` is `2026.1.0-edge.{height}` and `main` is a non-public NB.GV ref, so the actual edge version is **`2026.1.0-edge..g`** (e.g. `2026.1.0-edge.42.gfbb83ef`) — NB.GV-native height + commit, not a literal `` date. This satisfies the same goal (sortable, build-identifying, in the prerelease segment); a literal date stamp was not implemented because NB.GV does not produce one natively and the commit identifier is more precise. The original date-stamped examples in this ADR are illustrative of the *intent*, not the shipped string. - Edge publishes to **GitHub Packages only — never nuget.org.** This is consistent with *why* `main` was made non-publishing in ADR-0001: the pain was nuget.org Dependabot fan-out into every consumer repo. GitHub Packages is opt-in (consumers add the feed), so edge causes none of that fan-out. - Edge is **intentionally unstable.** This is the AI crowd's lane. -> The date belongs in the **prerelease segment**, not the version core. A core of `2026.05.29` would parse as year 2026 / minor 5 / patch 29 — a *stable* release under this scheme, not a nightly. `2026.2.0-edge.20260529.7` is the correct shape. +> The build identifier belongs in the **prerelease segment**, not the version core. A core of `2026.05.29` would parse as year 2026 / minor 5 / patch 29 — a *stable* release under this scheme, not a nightly. The prerelease-segment form is correct (see the implementation note above for the as-built `…-edge..g` string). ### 3. `release/YYYY` = the stable train @@ -77,7 +78,7 @@ The net property: **the fast lane never blocks on slow review, and the slow lane | Channel | Built from | Cadence | Version shape | Publishes to | Review tier | |---|---|---|---|---|---| -| **edge** | `main` | per-commit / daily | `2026.2.0-edge.20260529.` | GitHub Packages | light/fast | +| **edge** | `main` | per-commit | `2026.1.0-edge..g` (see §1 implementation note) | GitHub Packages | light/fast | | **preview / rc** | `release/YYYY` pre-GA | per cut | `2026.0.0-rc.2` | GitHub Packages | rigorous | | **stable** | `release/YYYY` tags | yearly major + non-breaking minor/patch | `2026.1.3` | nuget.org (opt-in) + GH Packages + GH Releases | rigorous | | **legacy** | `release/v10` (+ `hotfix/v10.x`) | security/critical only | `10.x` (semver) | nuget.org (opt-in) + GH Packages | rigorous | @@ -130,7 +131,7 @@ Dennis's suggestion: `develop` for integration, `main` for stable, `release/*` + Make daily builds literally `2026.05.29`. -**Rejected because** it collides with the CalVer core semantics — `2026.05.29` reads as a *stable* `MAJOR.MINOR.PATCH`, not a nightly — and there's no room left for minor/patch within a year. The date lives in the **prerelease segment** instead (`2026.2.0-edge.20260529.7`). +**Rejected because** it collides with the CalVer core semantics — `2026.05.29` reads as a *stable* `MAJOR.MINOR.PATCH`, not a nightly — and there's no room left for minor/patch within a year. The build identifier lives in the **prerelease segment** instead (the `…-edge.…` form — see the §1 implementation note for the as-built string). ## References diff --git a/docs/agents/release-and-versioning.md b/docs/agents/release-and-versioning.md index 961e3550f..bdb3fc65d 100644 --- a/docs/agents/release-and-versioning.md +++ b/docs/agents/release-and-versioning.md @@ -8,7 +8,7 @@ The branch/channel/versioning model is defined by [ADR-0004](../adr/0004-calenda Long-lived branches: -- `main` — integration trunk **and the published `edge` channel**. PRs target here. Every push (or a daily build) publishes a date-stamped prerelease `YYYY.MINOR.PATCH-edge..` to **GitHub Packages only** (never nuget.org). Edge is intentionally unstable — the fast/AI-assisted lane. Light/fast review. +- `main` — integration trunk **and the published `edge` channel**. PRs target here. Every push publishes an NB.GV-native prerelease `YYYY.MINOR.PATCH-edge..g` (e.g. `2026.1.0-edge.42.gfbb83ef`) to **GitHub Packages only** (never nuget.org). Edge is intentionally unstable — the fast/AI-assisted lane. Light/fast review. - `release/YYYY` (e.g. `release/2026`) — the **stable train** for the calendar year. Cut from `main`; hardened deliberately (slow crowd's domain, rigorous review). After the cut it takes **non-breaking minors + patches only** — never a breaking change. Tag-triggered releases fire from here. Protected per the policy below. - `release/v10` (+ `hotfix/v10.1`, `hotfix/v10.2`) — **legacy semver maintenance line**, `10.x`, **security and critical fixes only, no new features**. Not renumbered into CalVer. This line coexists indefinitely. - `release/v11` — **retired.** Nothing clean shipped under it (the `11.0.x` packages were unlisted); its rebrand/plugin work re-homed onto the `2026` line. Kept for archaeology, marked EoL — not a release target. @@ -46,7 +46,7 @@ Apply by mirroring `main`'s protection JSON to the new branch via the GitHub API - **`MAJOR` = year**, hand-set in `version.json` at the yearly cut. **`MINOR`** = feature drop within the year. **`PATCH`** = git-height fixes. - Per-branch via `version.json`. `main` carries the **next** planned version with an `-edge` prerelease tag (so edge builds sort above current stable). Each `release/YYYY` carries `"version": "YYYY.x"`; `release/v10` keeps `"version": "10.x"`. `publicReleaseRefSpec` matches **both** `^refs/heads/release/\d{4}$` and `^refs/heads/release/v\d+$`. -- Edge builds put the date in the **prerelease segment** (`2026.2.0-edge.20260529.`), never the version core — a core of `2026.05.29` would be a *stable* release, not a nightly. +- Edge builds carry the height + commit in the **prerelease segment** (`2026.1.0-edge..g`), never the version core — a core like `2026.05.29` would parse as a *stable* `MAJOR.MINOR.PATCH` release, not a nightly. (`main`'s `version.json` is `2026.1.0-edge.{height}` and `main` is intentionally a non-public ref, so NB.GV appends the `.g` suffix.) GitVersion is still installed as a transitional helper for `MajorMinorPatchVersion` in `Build.cs`; full removal is a follow-up. @@ -97,7 +97,7 @@ If you only discover the breaking nature mid-review, apply all relevant steps be ### Edge channel (from `main`) -Pushes to `main` publish **edge prereleases** (`YYYY.MINOR.PATCH-edge..`) to **GitHub Packages only** — never nuget.org, never a GitHub Release. This is the fast/AI-assisted lane; it is intentionally unstable and causes no nuget.org Dependabot fan-out into consumer repos (the reason `main` was made non-publishing in ADR-0001 — GitHub Packages is opt-in for consumers). _(Wiring tracked alongside ADR-0004 — see the milestone for the PR that adds the `main`-trigger edge job.)_ +Pushes to `main` publish **edge prereleases** (`YYYY.MINOR.PATCH-edge..g`) to **GitHub Packages only** — never nuget.org, never a GitHub Release. This is the fast/AI-assisted lane; it is intentionally unstable and causes no nuget.org Dependabot fan-out into consumer repos (the reason `main` was made non-publishing in ADR-0001 — GitHub Packages is opt-in for consumers). Implemented in `.github/workflows/edge.yml`. ### Why nuget.org stays opt-in diff --git a/docs/branching-and-release.md b/docs/branching-and-release.md index 3f1ce661a..28f9cb31b 100644 --- a/docs/branching-and-release.md +++ b/docs/branching-and-release.md @@ -22,7 +22,7 @@ Releases fire to multiple channels, each with its own GitHub Environment: | Channel | Built from | Cadence | Gating | Version shape | |---|---|---|---|---| -| **edge** → `github-packages` env | `main` | Per-commit / daily | None | `2026.2.0-edge..` | +| **edge** → `github-packages` env | `main` | Per-commit | None | `2026.1.0-edge..g` | | **stable** → `nuget-org` env | `release/YYYY` tags | Slow, deliberate | **Flag opt-in + approval-gated** | `2026.1.3` (CalVer) | | **stable/legacy** → `github-packages` env | `release/YYYY`, `release/v10` tags | Every tag | None | CalVer / `10.x` | | **legacy** → `nuget-org` env | `release/v10` tags | Security/critical only | **Flag opt-in + approval-gated** | `10.x` (semver) |