Skip to content

docs: align CONTRIBUTING/README/roadmap with CalVer + dual-pace channels (ADR-0004) #317

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 3 commits into from
May 29, 2026
Merged

docs: align CONTRIBUTING/README/roadmap with CalVer + dual-pace channels (ADR-0004) #317

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
51e0004
docs: align CONTRIBUTING/README/roadmap with CalVer + dual-pace chann…
ChrisonSimtian May 29, 2026
e1ca4f9
docs(readme): split edge.yml from release.yml in the Build Status table
ChrisonSimtian May 29, 2026
82d3384
Merge branch 'main' into docs/align-contributing-readme-calver
ChrisonSimtian May 29, 2026
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
20 changes: 11 additions & 9 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Fallout welcomes contributions. As a community, we want to help each other, prov

- Discuss non-trivial changes in an [issue](https://github.com/ChrisonSimtian/Fallout/issues) first.
- Small fixes (typos, broken links, tool wrapper additions) can go straight to a PR against `main`.
- Branch from `main`, open a PR against `main`. The trunk integrates everything; **releases ship from `release/vN` branches** (see [Branching and release flow](docs/branching-and-release.md) for the full model). The only time you target a release branch directly is for a maintainer-driven hotfix cherry-pick — and even then, the fix lands on `main` first.
- Branch from `main`, open a PR against `main`. `main` is the **edge channel** — the integration trunk and the fast/AI-assisted lane where everything lands first; **stable releases ship from `release/YYYY` branches** (the calendar-year stable train), and the legacy `release/v10` line takes security/critical fixes only (see [Branching and release flow](docs/branching-and-release.md) and [ADR-0004](docs/adr/0004-calendar-versioning-and-dual-pace-channels.md) for the full model). The only time you target a release branch directly is for a maintainer-driven hotfix cherry-pick — and even then, the fix lands on `main` first.

## Baseline contributions

Expand Down Expand Up @@ -50,9 +50,10 @@ Fallout welcomes contributions. As a community, we want to help each other, prov
### When writing the PR

- Aim for qualitative, readable code that matches the surrounding style.
- Don't fight `.editorconfig` or the ReSharper settings.
- There's no committed `.editorconfig` or ReSharper/`*.DotSettings` file — they were removed during the takeover. Rely on `dotnet format` defaults and review; don't reintroduce them without a maintainer-level decision.
- Add tests when meaningful — every `Foo` project has a sibling `Foo.Tests`.
- Don't commit code generated by `./build.ps1 GenerateTools` — generated `.cs` files are regenerated manually once per release.
- **Label the PR `target/YYYY`** for the calendar year it will release in — default `target/2026`. Legacy `release/v10` maintenance work uses `target/v10`. **Breaking changes are batched to the yearly major cut**: they may land on `main` only (never a `release/YYYY` stable train), are held for next year's `YYYY+1.0.0`, and additionally get a `breaking-change` label, a `⚠️ Breaking change` callout, and a `CHANGELOG.md` entry under the next-major `[Unreleased]` heading. Surface that isn't ready to commit to can ship behind `[Experimental("FALLOUT0xx")]` instead of being held back. See the [PR-creation flow](docs/agents/release-and-versioning.md#pr-creation-flow) for the full procedure.

### Tool wrappers

Expand All @@ -73,7 +74,8 @@ Tool wrapper JSON lives under `src/Fallout.Common/Tools/<Tool>/<Tool>.json`. Whe

### After opening a PR

- The PR gate is `ubuntu-latest` only — fires on PRs against `main` or any `release/vN` branch. Docs-only PRs hit a no-op shim workflow that reports the same status check name. `windows-latest` and `macos-latest` run post-merge on `main` for cross-platform validation (with `release/v*` push triggers tracked in [#293](https://github.com/ChrisonSimtian/Fallout/issues/293) as a parity follow-up).
- The PR gate is `ubuntu-latest` only — fires on PRs against `main` or any `release/*` branch. Docs-only PRs hit a no-op shim workflow that reports the same status check name. `windows-latest` and `macos-latest` run post-merge on `main` for cross-platform validation (with `release/*` push triggers tracked in [#293](https://github.com/ChrisonSimtian/Fallout/issues/293) as a parity follow-up).
- **Review is two-tier.** PRs to `main` (edge) get light, fast review — edge is intentionally unstable and no production consumer tracks it. Promotion to a `release/YYYY` stable train (and the GA cut) gets rigorous, unhurried review — that's the project's quality gate. Match your expectations to where the PR is headed.
- Address review feedback in additional commits rather than force-pushing — easier to review the changes.
- If CI fails on something unrelated to your change, ping a maintainer.

Expand All @@ -89,11 +91,11 @@ The merger (typically a CODEOWNER) picks the button; the PR description can requ

## Releases

Merging to `main` doesn't publish anything — it's the integration trunk. Releases fire from `release/vN` branches via tag push, with a multi-channel publish fan-out (nuget.org, GitHub Packages, GitHub Releases). The full lifecycle is documented in [docs/branching-and-release.md](docs/branching-and-release.md):
Merging to `main` publishes an **edge prerelease** (`2026.MINOR.PATCH-edge.…`) to **GitHub Packages only** — never nuget.org. `main` is the integration trunk *and* the intentionally-unstable edge channel. **Stable releases** fire from `release/YYYY` branches via tag push, with a multi-channel publish fan-out (GitHub Packages + GitHub Releases by default; nuget.org is **opt-in**). The full lifecycle is documented in [docs/branching-and-release.md](docs/branching-and-release.md):

- How releases happen (tag a `release/vN` branch, three parallel publish jobs)
- The channel taxonomy (Tier 1 nuget.org, Tier 2 GitHub Packages, Tier 3 Docker local for pre-merge)
- Hotfix flow (cherry-pick from `main` to `release/vN`)
- When to cut a new `release/vN`
- How releases happen (tag a `release/YYYY` branch, parallel publish jobs)
- The channel taxonomy (edge → GitHub Packages; stable → GitHub Packages + GitHub Releases, nuget.org opt-in; Docker local for pre-merge)
- Hotfix flow (cherry-pick from `main` to `release/YYYY`; the legacy `release/v10` line takes security/critical fixes directly)
- When to cut a new `release/YYYY`

Contributors don't usually need to do any of this — releases are maintainer-driven. But if you're filing a PR labelled `target/v<N>` where N is older than the current major, expect the maintainer to cherry-pick it to `release/vN` after merging to `main`.
Contributors don't usually need to do any of this — releases are maintainer-driven. But if you're filing a PR labelled `target/v10` (legacy maintenance) or one that carries a breaking change held for next year's major, expect the maintainer to route it accordingly after merging to `main`.
16 changes: 11 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,11 +25,13 @@
[![GitHub Sponsors](https://img.shields.io/github/sponsors/ChrisonSimtian?label=sponsor&logo=githubsponsors&color=EA4AAA)](https://github.com/sponsors/ChrisonSimtian)

> [!IMPORTANT]
> **Rebrand in progress + v11/v12 roadmap published.** This repository is being renamed from **NUKE** to **Fallout** as part of a hard fork. URLs, package names, and namespaces are migrating in stages.
> **Rebrand in progress + roadmap published.** This repository is being renamed from **NUKE** to **Fallout** as part of a hard fork. URLs, package names, and namespaces are migrating in stages.
>
> **What's next:** v11 finishes the rebrand and lays the internal foundation for a plugin architecture; v12 ships the public `Fallout.Plugin.Sdk`. The full plan is in [**docs/roadmap.md**](docs/roadmap.md). Five RFCs are open now to shape the SDK — your input matters most before v12 firms up.
> **Versioning & channels.** Fallout ships on **calendar versions** (`YYYY.MINOR.PATCH`; the major is the year). `main` is the fast, intentionally-unstable **edge** channel; the `release/YYYY` **stable train** carries non-breaking minors/patches after the yearly cut. See [ADR-0004](docs/adr/0004-calendar-versioning-and-dual-pace-channels.md) and [docs/branching-and-release.md](docs/branching-and-release.md).
>
> Track v11 in [milestone #6](https://github.com/ChrisonSimtian/Fallout/milestone/6) and v12 in [milestone #7](https://github.com/ChrisonSimtian/Fallout/milestone/7).
> **What's next:** the rebrand completes and the internal foundation for a plugin architecture lands on the 2026 line; a later major ships the public `Fallout.Plugin.Sdk`. The full plan is in [**docs/roadmap.md**](docs/roadmap.md). Five RFCs are open now to shape the SDK — your input matters most before it firms up.
>
> Track the work in [milestone #6](https://github.com/ChrisonSimtian/Fallout/milestone/6) (rebrand + plugin foundation) and [milestone #7](https://github.com/ChrisonSimtian/Fallout/milestone/7) (public plugin SDK).

## Based on NUKE

Expand Down Expand Up @@ -64,6 +66,9 @@ The CLI installs as `fallout`. Verify with `fallout --help`.

For per-repo manifest pinning (`.config/dotnet-tools.json`), project setup, and shell completion, see the [Installation guide on docs.fallout.build](https://docs.fallout.build/getting-started/installation).

> [!NOTE]
> **Channels.** Stable releases ship on **calendar versions** (`YYYY.MINOR.PATCH`, e.g. `2026.1.3`; the major is the year) from the `release/YYYY` train — published to GitHub Packages, with nuget.org publishing opt-in per release. A faster, intentionally-unstable **edge** prerelease (`2026.MINOR.PATCH-edge.…`) is published from `main` to **GitHub Packages only**; opt in by adding the GitHub Packages feed if you want to track the bleeding edge. The legacy NUKE `10.x` line stays on semver and receives security/critical fixes only. See [ADR-0004](docs/adr/0004-calendar-versioning-and-dual-pace-channels.md) and [docs/branching-and-release.md](docs/branching-and-release.md) for the full model.

## Table of Contents

- [Elevator Pitch](#elevator-pitch)
Expand All @@ -79,14 +84,15 @@ Fallout (NUKE's successor) brings your build automation to an even level with ev

## Build Status

CI runs on every PR targeting `main` across `ubuntu-latest` — the only required status check. After merge to `main`, post-merge validation runs on `windows-latest` and `macos-latest`. Releases publish from `main` to **nuget.org** under the reserved `Fallout.*` prefix, via `.github/workflows/release.yml`. Docs-only PRs are served by a no-op companion workflow (`ubuntu-latest-docs`) so branch protection is satisfied without spending CI minutes on a real build.
CI runs on every PR targeting `main` across `ubuntu-latest` — the only required status check. After merge to `main`, post-merge validation runs on `windows-latest` and `macos-latest`, and an **edge** prerelease is published to **GitHub Packages** under the reserved `Fallout.*` prefix. **Stable** releases fire from `release/YYYY` tags via `.github/workflows/release.yml` (GitHub Packages + GitHub Releases by default; nuget.org opt-in per release). Docs-only PRs are served by a no-op companion workflow (`ubuntu-latest-docs`) so branch protection is satisfied without spending CI minutes on a real build.

| Workflow | Status | Trigger |
|---|---|---|
| [`ubuntu-latest`](.github/workflows/ubuntu-latest.yml) | [![ubuntu-latest](https://img.shields.io/github/actions/workflow/status/ChrisonSimtian/Fallout/ubuntu-latest.yml?branch=main&label=&logo=ubuntu&logoColor=white&style=flat-square)](https://github.com/ChrisonSimtian/Fallout/actions/workflows/ubuntu-latest.yml) | PR to `main` (code paths) — **required check** |
| [`windows-latest`](.github/workflows/windows-latest.yml) | [![windows-latest](https://img.shields.io/github/actions/workflow/status/ChrisonSimtian/Fallout/windows-latest.yml?branch=main&label=&logo=windows&logoColor=white&style=flat-square)](https://github.com/ChrisonSimtian/Fallout/actions/workflows/windows-latest.yml) | push to `main` (post-merge validation) |
| [`macos-latest`](.github/workflows/macos-latest.yml) | [![macos-latest](https://img.shields.io/github/actions/workflow/status/ChrisonSimtian/Fallout/macos-latest.yml?branch=main&label=&logo=apple&logoColor=white&style=flat-square)](https://github.com/ChrisonSimtian/Fallout/actions/workflows/macos-latest.yml) | push to `main` (post-merge validation) |
| [`release`](.github/workflows/release.yml) | [![release](https://img.shields.io/github/actions/workflow/status/ChrisonSimtian/Fallout/release.yml?branch=main&label=&logo=nuget&logoColor=white&style=flat-square)](https://github.com/ChrisonSimtian/Fallout/actions/workflows/release.yml) | push to `main` — publishes `Fallout.*` to nuget.org |
| [`edge`](.github/workflows/edge.yml) | [![edge](https://img.shields.io/github/actions/workflow/status/ChrisonSimtian/Fallout/edge.yml?branch=main&label=&logo=githubactions&logoColor=white&style=flat-square)](https://github.com/ChrisonSimtian/Fallout/actions/workflows/edge.yml) | push to `main` → edge prerelease to GitHub Packages |
| [`release`](.github/workflows/release.yml) | [![release](https://img.shields.io/github/actions/workflow/status/ChrisonSimtian/Fallout/release.yml?branch=main&label=&logo=nuget&logoColor=white&style=flat-square)](https://github.com/ChrisonSimtian/Fallout/actions/workflows/release.yml) | tag push on `release/YYYY` (stable) or `release/v10` (legacy) — nuget.org opt-in |

Multi-provider CI support (Azure Pipelines, GitLab, TeamCity, AppVeyor) was removed during the takeover and is being revived demand-driven — see [#8](https://github.com/ChrisonSimtian/Fallout/issues/8).

Expand Down
Loading