[P5] Decide bridge strategy for existing NUKE consumers

[ChrisonSimtian]

Question

How do existing NUKE users — those with build scripts containing `using Nuke.Common; class Build : NukeBuild` — migrate to Fallout?

Constraint

We don't own the `Nuke.*` package IDs on nuget.org. Matt does. So we cannot publish typeforwarding shims under `Nuke.Common` on nuget.org. We could ship them on GitHub Packages but users would need to opt into our feed.

Options

A. Roslyn codefix in Fallout.Common

Ship an analyzer that detects `using Nuke.*` and offers a one-click rewrite. Lowest user effort post-install. Doesn't help users who haven't installed Fallout yet (chicken-and-egg).

B. Standalone migration CLI tool

`dotnet tool install -g Fallout.Migrate` → run in repo → rewrites `using` directives, replaces PackageReferences, suggests bootstrap script updates. Heavier lift to build but works end-to-end.

C. Manual migration guide

Step-by-step doc, optionally with sed/PowerShell scripts users can copy. Zero tooling work, highest user effort.

D. Type-forwarding shim packages

Ship `Fallout.Compat.Nuke.Common` package that re-exports `Fallout.Common` types under the `Nuke.Common` namespace via `[TypeForwardedTo]`. Users PackageReference this single bridge and old `using` directives keep working. Trade-off: keeps the NUKE namespace alive forever.

E. Hybrid (recommended)

• A (codefix) for the simple cases
• C (manual guide) for documentation
• B (CLI tool) deferred until demand justifies it
• D explicitly avoided — we want the namespace transition clean

Done when

• Decision documented here
• Implementation issue(s) opened for the chosen approach
• Migration timeline drafted (when does `Nuke.*` support sunset?)

[ChrisonSimtian]

Chosen strategy: A + B + C + D (kitchen sink)

Going broader than the originally recommended hybrid. Existing NUKE users are an enterprise audience; migration friction has to be near-zero or they stay on nuke-build/nuke 10.x. Accepting the trade-off of keeping Nuke.* namespace surface area alive longer than ideal in exchange for genuine drop-in migration.

What ships

Layer	What it does	User experience
D. Type-forwarding shim packages	Fallout.Compat.Nuke.Common etc. — re-export Fallout.Common types under the Nuke.Common namespace via [TypeForwardedTo].	Zero source-code change. Swap a PackageReference and using Nuke.* keeps compiling.
B. Migrator CLI tool	dotnet tool install -g Fallout.Migrate → rewrites using directives, PackageReferences, [Nuke...] attributes, and bootstrap scripts in one pass.	One command, full repo migrated.
A. Roslyn codefix (#36)	IDE lightbulb on every using Nuke.*.	Per-file/per-line interactive migration.
C. Migration guide (#37)	docs/migration/from-nuke.md.	Explains all of the above and when to use which.

Constraint check: nuget.org

The Nuke.* package IDs on nuget.org are still owned upstream. The shim packages therefore ship as Fallout.Compat.Nuke.<X> — not Nuke.<X>. The compat package's internal namespace is Nuke.<X> (so consumer using Nuke.X; keeps resolving), but the package ID is Fallout-prefixed. ~95% of the source-compatibility value without needing nuget.org ownership.

Sunset timeline (proposal)

• 0–12 months post-rename: shims published alongside every Fallout release.
• 12–24 months: shim packages move to maintenance-only (security fixes only).
• 24+ months: shims archived; migration tools remain.

Follow-up

• Implementation issue for shim packages (Fallout.Compat.Nuke.*) — opening separately.
• Implementation issue for the migrator CLI tool (Fallout.Migrate) — opening separately.
• [P5] Build Roslyn codefix for Nuke.* → Fallout.* using directives #36 already covers the Roslyn codefix.
• [P5] Write NUKE → Fallout migration guide #37 already covers the migration guide.
• [P3] Plan: Nuke.* → Fallout.* namespace mapping #31 needs an update: mapping must stay strict 1:1 (no consolidation), otherwise shims can't TypeForwardedTo cleanly.

[ChrisonSimtian]

Amendment: shim packages reuse the Nuke.* IDs on our GH Packages feed

The earlier strategy comment proposed Fallout.Compat.Nuke.<X> as the shim package IDs to avoid colliding with upstream's nuget.org ownership. Refined position: GitHub Packages is our own feed — ChrisonSimtian/Nuke.Common lives in a different ID-space from nuget.org/Nuke.Common. So we can simply publish Nuke.<X> packages on our GH feed without any collision.

This collapses three things into a much cleaner bridge:

Revised shim architecture (β)

The codebase still renames internally to Fallout.*. We then publish two parallel package families to our GH Packages feed:

• Fallout.<X> 11.x — canonical, real types in Fallout.* namespace.
• Nuke.<X> 11.x — depends on Fallout.<X>, contains only [assembly: TypeForwardedTo(typeof(Fallout.<X>.SomeType))] declarations, exposes the Nuke.<X> namespace surface.

What that means for a NUKE consumer

Migration becomes:

1. Add our GH Packages source to nuget.config.
2. Bump <PackageReference Include="Nuke.Common" Version="11.0.0" />.
3. Done. using Nuke.Common; keeps compiling.

No package ID change. No namespace change in their source. They can later migrate to native Fallout.<X> at their own pace — or stay on the Nuke.<X> shim indefinitely.

Scope boundary

The Nuke.<X> packages on our GH Packages feed are bridge artifacts, not a successor brand. The successor identity is Fallout — repo, docs, comms, eventual nuget.org publication. Publishing transient Nuke.<X> shim packages on a private feed during migration is consistent with the spirit of the original maintainer's "name can't be carried over" position.

Impact on related issues

• [P5] Ship Nuke.* type-forwarding shim packages on our GH Packages feed #47 — repurposed: shim packages are now just Nuke.<X>, not Fallout.Compat.Nuke.<X>. Updating the issue body to reflect this.
• [P5] Build Fallout.Migrate CLI tool — automated NUKE → Fallout repo migration #48 (Fallout.Migrate CLI) — PackageReference rewriting becomes optional. The CLI's default path: leave Nuke.<X> IDs alone, just bump versions and add the GH Packages feed. A --rename-packages flag offers the harder cutover.
• [P5] Build Roslyn codefix for Nuke.* → Fallout.* using directives #36 (Roslyn codefix) — unchanged.
• [P5] Write NUKE → Fallout migration guide #37 (migration guide) — needs to document both paths: "stay on Nuke.<X> (easiest)" vs "cut over to Fallout.<X>".
• [P3] Plan: Nuke.* → Fallout.* namespace mapping #31 — strict 1:1 prefix-swap mapping still required (TypeForwarders need name parity).