Fallout-build / Fallout-build/Fallout
Normalise the package-id / project-name relationship so renames stop moving published ids
- Dominant language
- C#
- Stars
- 154
- Forks
- 19
- Avg merge
- 1d 22h
- Merged PRs (30d)
- 15
Description
### Problem
The dotnet tool's NuGet package id has changed three times in about a year. Two of those changes were published to nuget.org and had to be cleaned up by unlisting versions. There is no written rule for how a package id relates to the project and assembly that produce it. Each project rename has pulled the package id along with it.
What happened so far:
| Change | Where | Published under the old id |
|---|---|---|
| `Nuke.GlobalTool` → `Fallout.GlobalTool` | 6967a094, the Nuke → Fallout rebrand | 52 versions, `10.2.12` to `10.3.49` |
| `Fallout.GlobalTool` → `Fallout.Cli` | project rename, id followed | `10.3.41`–`10.3.47`, `11.0.1`–`11.0.18`, all now unlisted |
| `Fallout.Cli` → `Fallout.GlobalTools` | f0208100 | `10.4.0-rc.4` |
| `Fallout.GlobalTools` → `Fallout.GlobalTool` | #581 | returns to the id the existing users already have |
Cost so far: two unlisting sweeps, one draft migration guide written and then deleted, and a repo-wide docs sweep each time.
The onion-architecture migration (milestone #6) will rename many more projects. Without a rule, package ids keep moving with them.
### Outcome
A written rule that separates two kinds of name:
- **Internal names** — project, assembly, namespace. Free to change as the architecture moves.
- **Consumer contract** — the NuGet package id. Does not change when a project is renamed.
Renaming a project stops being able to change what consumers install. When an id genuinely has to change, there is one documented process for it instead of an ad-hoc decision each time.
### Acceptance criteria
- [ ] ADR records the rule: package id is a consumer contract, internal names are not.
- [ ] Every packable project sets `PackageId` explicitly, so it never defaults to the assembly name and never moves by accident.
- [ ] One document lists every published package id and the project that produces it.
- [ ] A build check fails when a packable project has no explicit `PackageId`, or when the set of ids does not match that list.
- [ ] The rule states the naming pattern new packages follow, so future ids are consistent from the start.
- [ ] The rule states that any future normalisation of existing ids happens once, at a yearly major cut, batched with other breaking changes, with a migration guide and a nuget.org deprecation. It does not happen incrementally.
- [ ] [docs/agents/conventions.md](../blob/main/docs/agents/conventions.md) links the rule.
- [ ] `Fallout.GlobalTools 10.4.0-rc.4` is deprecated on nuget.org with `Fallout.GlobalTool` as the alternate package.
### Notes
- #581 stops the current churn and reverts to `Fallout.GlobalTool`. This issue covers the durable rule, not that revert.
- #576 rewrites the tool pin in consumer `.config/dotnet-tools.json` files. Whatever id this issue settles on is the id that step must write.
- The decoupling itself is already in place and worth keeping: `Fallout.Cli` packs as `Fallout.GlobalTool`, and `build/Build.cs` now reads the id from the csproj rather than assuming it matches the project name.
Contributor guide
Assessment
This issue has not been assessed yet.