Skip to content

docs: correct edge version shape to the as-built NB.GV form #319

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ChrisonSimtian merged 1 commit into from
May 29, 2026
Merged

docs: correct edge version shape to the as-built NB.GV form #319

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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 AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.<YYYYMMDD>.<h>`) to **GitHub Packages only**. Light/fast review.
- **`main` = the edge channel** — fast/AI-assisted, intentionally unstable, per-commit prereleases (`2026.1.0-edge.<height>.g<commit>`, 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).
Expand Down
9 changes: 5 additions & 4 deletions docs/adr/0004-calendar-versioning-and-dual-pace-channels.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.<YYYYMMDD>.<height>`. 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.<height>.g<commit>`** (e.g. `2026.1.0-edge.42.gfbb83ef`) — NB.GV-native height + commit, not a literal `<YYYYMMDD>` 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.<height>.g<commit>` string).

### 3. `release/YYYY` = the stable train

Expand Down Expand Up @@ -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.<h>` | GitHub Packages | light/fast |
| **edge** | `main` | per-commit | `2026.1.0-edge.<height>.g<commit>` (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 |
Expand Down Expand Up @@ -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

Expand Down
6 changes: 3 additions & 3 deletions docs/agents/release-and-versioning.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.<YYYYMMDD>.<h>` 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.<height>.g<commit>` (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.
Expand Down Expand Up @@ -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.<h>`), 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.<height>.g<commit>`), 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<commit>` suffix.)

GitVersion is still installed as a transitional helper for `MajorMinorPatchVersion` in `Build.cs`; full removal is a follow-up.

Expand Down Expand 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.<YYYYMMDD>.<h>`) 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.<height>.g<commit>`) 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

Expand Down
2 changes: 1 addition & 1 deletion docs/branching-and-release.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.<YYYYMMDD>.<h>` |
| **edge** → `github-packages` env | `main` | Per-commit | None | `2026.1.0-edge.<height>.g<commit>` |
| **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) |
Expand Down