Fallout→Fallout upgrades break at compile time with no signposting to fallout-migrate (10.3→10.4 CS0246 on Project)

[ChrisonSimtian]

@

Problem

Upgrading a consumer build from Fallout.Common 10.3.49 to 10.4.0-rc.5 fails to compile:

Build.cs(160,5): error CS0246: The type or namespace name 'Project' could not be found

Reproduced on FluentAssertions (a real consumer already on Fallout 10.3.49) changing only <FalloutVersion>. Exactly 1 error, 0 warnings.

Solution and Project moved from Fallout.Common.ProjectModel to Fallout.Solutions. The transition shim in src/Fallout.Common/ProjectModel/TransitionShims.cs is shipped in rc.5, but is shallow by design — verified from the rc.5 package's own XML docs, it contains only:

T:Fallout.Common.ProjectModel.Solution
T:Fallout.Common.ProjectModel.SolutionAttribute

Project is deliberately not shimmed. So using Fallout.Common.ProjectModel; keeps compiling and Solution keeps resolving — the build breaks only where the consumer touches Project. The rename is not half-applied; this is the documented shim ceiling.

fallout-migrate 10.4.0-rc.5 already has the rewrite rule (RewriteCsFilesStep.projectModelNamespace, matching both Nuke. and Fallout. prefixes) and fully fixes this. Verified end-to-end: running it on the already-Fallout FluentAssertions repo rewrote using Fallout.Common.ProjectModel; → using Fallout.Solutions; and the build went green.

So the defect is not a missing rewrite — it is that nothing leads a consumer to the fix.

• fallout-migrate's own description is "Migrate a NUKE consumer repo to Fallout". A maintainer bumping 10.3 → 10.4 has no reason to think it applies to them.
• Its other steps are NUKE-specific (RenameNukeDirectoryStep, RewriteBootstrapScriptsStep, ResolveFalloutVersionStep pinning "latest stable in-major").
• The consumer just sees CS0246 and hand-fixes it. The one-line fix is using Fallout.Common.ProjectModel; → using Fallout.Solutions;.

Secondary, same run: on an already-Fallout repo RewriteCsprojsStep strips the explicit System.Security.Cryptography.Xml pin (see #618) and leaves its explanatory comment orphaned above nothing, plus de-indents the closing </PropertyGroup>/</ItemGroup> tags.

Outcome

A consumer bumping a Fallout version either does not break, or is told exactly what to run.

Acceptance criteria

• 10.4.0 release notes / upgrade guide state that Fallout.Common.ProjectModel → Fallout.Solutions and that fallout-migrate performs the rewrite
• Reframe fallout-migrate so a Fallout→Fallout version bump is an advertised use case, not just NUKE→Fallout (see the version-wise migration proposal — separate issue/PR)
• Decide: extend the shim to cover Project, or leave the ceiling and rely on documentation + migrate
• Consumer-upgrade smoke test (10.3.x source compiled against the next minor) so this is caught before GA — fallout.canary is the natural home
• Fix the orphaned-comment / de-indentation fallout in RewriteCsprojsStep

Correction

The original text of this issue claimed there was no transition shim, no type-forwarding, and no fallout-migrate rule, and carried a breaking-change label. That was wrong — it was based on a local release/v10.4 ref that was 32 commits behind the v10.4.0-rc.5 tag. Both the shim and the migrate rule exist at the tag. Body corrected and the label removed; the compile break and the signposting gap are real and reproduced.
@

[ChrisonSimtian]

Corrected the body — see the Correction section. My original claims that there was no transition shim and no fallout-migrate rule were based on a stale local release/v10.4 ref (32 commits behind the v10.4.0-rc.5 tag). Both exist at the tag, and fallout-migrate does fix the break end-to-end (verified: FluentAssertions builds clean after running it). Removed the breaking-change label accordingly — the shim keeps Solution compiling, and the reachable break is scoped to Project. What remains is the signposting gap, retitled to match.

[ChrisonSimtian]

Consumer-upgrade smoke test is built — Fallout-build/Fallout.Canary#7, scenario upgrade (pending merge).

It pins a 10.3-era consumer, bumps only the version, and asserts they reach green in three stages: build at the baseline (must pass), bump the version and change nothing else, then fall back to fallout-migrate — failing only if migrate can'"'"'t get them to green either. A rough upgrade is a pass; a dead-end upgrade is a failure. Which path was taken goes to the run summary, since needing the migrator means the release notes owe an upgrade note.

Build.cs there is deliberately un-modernised and navigates the project graph (Solution.GetProject("Sample") returning Project) rather than only declaring a Solution — which is exactly the line between what the transition shim covers and what it does not.

Verified green end to end:

baseline 10.3.49       → green
bump to 10.4.0-rc.5    → error CS0246: 'Project' could not be found   (1 error, 0 warnings)
fallout-migrate        → using Fallout.Common.ProjectModel; → using Fallout.Solutions;
rebuild + re-run       → green

The baseline is pinned (bumped once per production line); the target floats as "newest listed on nuget.org", which is the current line because previews only ever go to GitHub Packages. So the hop becomes 10.3.49 → 10.4.0 the moment GA ships with no edit, and the scenario keeps guarding every subsequent line.

Input for the open shim decision

Extending the shim to cover Project looks cheap and is not. Every way a consumer obtains one — GetProject(name), AllProjects, Projects, GetAllProjects(pattern) in src/Persistence/Fallout.Solution/Model.cs — returns the canonical Fallout.Solutions.Project, and instances are constructed on the canonical type via GetOrCreate<Project>. A Fallout.Common.ProjectModel.Project : Fallout.Solutions.Project subclass would make the name resolve and then turn Project p = Solution.GetProject("X") into CS0266, because canonical → shim is a downcast. It would also define a type the library never produces an instance of.

That trades a self-explanatory error ("the namespace moved", fixed by one using change) for a confusing one ("two identically-named Project types"). The Solution shim only works because SolutionAttribute deserializes into the annotated member'"'"'s declared type, so a shim-typed instance is genuinely constructed. There is no equivalent hook for Project.

The cheaper lever for the signposting gap is src/Fallout.Migrate.Analyzers/NukeMigrationAnalyzer.cs, which already flags a legacy using and ships a codefix — extending it to Fallout.Common.ProjectModel → Fallout.Solutions is a handful of lines against an existing mechanism. Caveat: Fallout.Migrate.Analyzers is a separate package Fallout.Common does not reference, so consumers don'"'"'t get it by default. Making Fallout.Common carry the analyzer is its own call.

[IT-VBFK]

#614 would fix the indentation bug

[IT-VBFK]

What about triggering a fallout-migrate on every nuget restore?
Maybe with a dedicated csproj option like <FalloutAutoMigrate> or similar.
This would adopt repos as they update the FalloutVersion.

[ChrisonSimtian]

What about triggering a fallout-migrate on every nuget restore? Maybe with a dedicated csproj option like <FalloutAutoMigrate> or similar. This would adopt repos as they update the FalloutVersion.

#625

I like this idea, lets discuss further in a dedicated issue :-)