Fallout-build / Fallout-build/Fallout

RFC: Release management strategy — backports, release branches, version-locked support

Open
#227 0 comments 0 reactions 0 assignees View on GitHub
enhancement RFC target/vNext
Dominant language
C#
Stars
154
Forks
19
Avg merge
1d 22h
Merged PRs (30d)
15

Description

## Why now
Surfaced from #217: @dennisdoomen hit a real bug on `10.3.45` while migrating FluentAssertions. We fixed it in [#226](https://github.com/ChrisonSimtian/Fallout/pull/226), which lands on `11.0.x`. Dennis can hand-apply the patch to a 10.3.x checkout, but: should we have a documented release-management policy so this scales beyond "one prominent dev can hand-patch"?

Context: we just shipped v11 and have v12 (Public Plugin SDK) + v13 (Continuous Delivery) milestones queued. More consumers means more "I'm on 11.0 and can't move to 12.0 yet — can you backport this fix?" reports. We need a coherent answer.

## Status quo (implicit)
All fixes land on `main`, released under the current major (e.g. `11.0.x`). No backports. Consumers on older majors either:
1. Upgrade to the current major (sometimes blocked by their own constraints).
2. Pin to their 10.3.x and live with the bug.
3. Maintain a private fork with hand-applied patches.

Fine for a small project; scales badly for "build framework with many enterprise consumers" — the v13 trajectory.

## Options

### A. Status quo — main only, roll forward
- **Pros:** zero process overhead. One branch. Every fix benefits from latest code.
- **Cons:** users on older majors can't get just-the-fix. Weak trust signal for enterprises planning multi-year LTS.

### B. Release branches with version-locked patch releases
- Cut `release/v{major}` at every major bump (e.g. `release/v11` at the `11.0` cut).
- Backport-worthy fixes cherry-picked from `main` onto each active release branch.
- Each branch ships its own patch line (`11.0.x` from `release/v11`, `12.0.x` from `release/v12`).
- Explicit support window — e.g. "security fixes to the previous major for N months after a new major ships; bug fixes to the current major only".
- **Pros:** clear contract. Enterprises can pin to a major and trust they'll get fixes. Matches how dotnet ships LTS branches.
- **Cons:** every fix needs triage ("backport to v10? v11?"). Cherry-pick conflicts accumulate. Needs automation (`backport` label, GH bot).

### C. Long-lived support branches with version in the branch name
- e.g. `release/v11.0.x`, `release/v11.1.x`, `release/v12.0.x`. Branch name encodes the version line.
- More granular than B — each minor gets its own branch.
- **Pros:** very explicit; easy to know what's where.
- **Cons:** branch proliferation. Best when minors are common, not pure-patch lines.

### D. Hand-patch on request — current behaviour, documented
- Same as A, but published: "we support only `latest` of the current major. Backports are not provided; consumers can hand-apply patches from `main`."
- README / CONTRIBUTING.md gets a short "Support policy" section.
- **Pros:** cheapest. Sets expectations honestly. Removes ambiguity.
- **Cons:** weaker enterprise story. Doesn't scale.

## Open questions
1. **Minimum support window?** "Current major only" / "Current + N-1" / "Current + N-1 + N-2 (LTS)".
2. **Who decides backport-worthiness?** Maintainer call vs. label-driven (`backport:v10`) vs. triage rules.
3. **Tooling:** a `backport` label, GH workflow auto-cherry-picking labelled PRs, conflict-handling story.
4. **CI cost:** each active release branch costs CI minutes for its own ubuntu/macos/windows runs.
5. **CHANGELOG model:** per-branch sections, or single CHANGELOG with version markers?
6. **Versioning:** Nerdbank.GitVersioning's `publicReleaseRefSpec` must include the release branches. Branch-name pattern matters.

## Recommendation (mine, for the record)
For v11→v12: **start with (D)** — document support as "main / current major only". Watch backport-request frequency. If 3+ enterprise-shaped consumers ask within a quarter, escalate to (B) with "security fixes to v(N-1) for 6 months after vN ships". Don't pre-build machinery before there's demand.

## Refs
- Triggering issue: #217 (Dennis on 10.3.45 hit a bug fixed in 11.0.x).
- Triggering fix: #226 (lands on `main` → 11.0.x only).
- Semver context: #220, [`CLAUDE.md` Semver policy](https://github.com/ChrisonSimtian/Fallout/blob/main/CLAUDE.md).

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.