[P5] Ship Nuke.* type-forwarding shim packages on our GH Packages feed #47

Revised 2026-05-19: shim packages are now published as Nuke.<X> on our GitHub Packages feed (not Fallout.Compat.Nuke.<X>). See the strategy amendment on #35 for the why.

Implementation issue spun off from #35 (bridge strategy).

Goal

Provide drop-in source compatibility for existing NUKE consumers. A user adds our GitHub Packages feed to their nuget.config, bumps their Nuke.Common version to 11.x, and everything else (PackageReferences, using directives, code) keeps working unchanged.

How it works

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

• Fallout.<X> 11.x — canonical packages. Real types in the Fallout.<X> namespace.
• Nuke.<X> 11.x — bridge packages. Depend on the matching Fallout.<X> package; contain only [assembly: TypeForwardedTo(typeof(Fallout.<X>.SomeType))] declarations; expose the Nuke.<X> namespace surface.

So a consumer goes from:

<PackageReference Include="Nuke.Common" Version="10.1.0" />

to:

<PackageReference Include="Nuke.Common" Version="11.0.0" />

…with a nuget.config change to add our GH Packages source. Their using Nuke.Common; and class hierarchies (: NukeBuild) keep compiling unchanged.

Why the Nuke.<X> ID works on our feed

GitHub Packages namespaces are per-org/user — ChrisonSimtian/Nuke.Common is a different package from nuget.org/Nuke.Common. We are not colliding with the upstream ID, only providing a same-named bridge package within our own scope. Consumers opt in by adding our feed.

Scope of shims

One shim package per consumer-facing namespace:

• Nuke.Common
• Nuke.Build
• Nuke.Components
• Nuke.Tooling
• Nuke.Utilities (+ sub-packages: IO.Compression, IO.Globbing, Net, Text.Json, Text.Yaml)
• Nuke.ProjectModel
• Nuke.SolutionModel

Internal-only namespaces (Nuke.Tooling.Generator, Nuke.SourceGenerators, Nuke.MSBuildTasks) don't need shims — consumers don't reference them directly.

Implementation approach

• New project layout: source/compat/Nuke.<X>/Nuke.<X>.csproj. Sibling to the canonical source/Fallout.<X>/.
• Generate the [TypeForwardedTo] declarations from a build target — read public types from Fallout.<X>.dll, emit a TypeForwarders.g.cs per shim.
• Shim assemblies should not contain any real code — purely forwarders.
• Both Nuke.<X> and Fallout.<X> ship at the same version.

Open questions

• Generic types and types with private constructors — do they forward cleanly? Audit on a sample.
• Internal types referenced via InternalsVisibleTo — do they leak into the public surface anywhere? If so they cannot forward.
• Attribute types ([GitHubActions(...)] etc.) — do they forward cleanly across assemblies? Verify.

Done when

• One shim package per namespace above.
• Build target auto-generates TypeForwardedTo declarations from public types.
• Sample consumer project compiles unchanged when bumping <PackageReference Include="Nuke.Common" Version="11.0.0" /> against our GH Packages feed.
• Shims published to GitHub Packages alongside Fallout.<X> packages.
• Documented in the migration guide ([P5] Write NUKE → Fallout migration guide #37) as the "easiest path" — also documents the nuget.config setup.

Dependencies

• Blocked by [P3] Execute solution-wide Nuke.* → Fallout.* namespace rename (BREAKING) #32 (Fallout.* types must exist to forward to).
• Blocked by [P4] Reserve Fallout.* package IDs on nuget.org #33 (canonical Fallout.<X> package IDs reserved on our feed).
• Locks [P3] Plan: Nuke.* → Fallout.* namespace mapping #31 to strict 1:1 mapping (TypeForwarders need exact type-name match).

Scope boundary

These Nuke.<X> shim packages exist only on our GitHub Packages feed during the migration window. They are bridge artifacts, not a successor brand. The successor brand is Fallout — repo, docs, comms, eventual nuget.org publication.