Fallout-build / Fallout-build/Fallout

Normalise the package-id / project-name relationship so renames stop moving published ids

Open
#582 0 comments 0 reactions 1 assignee Claimed by @ChrisonSimtian View on GitHub
ADR documentation
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

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.