diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6e5e48dc..ab54ba71 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -44,7 +44,7 @@ Fallout welcomes contributions. As a community, we want to help each other, prov - Branch from `main` (the base for all PRs). Name your branch `feature/`, `bugfix/`, or `chore/`. - Make sure your employer allows the contribution. - Read [AGENTS.md](AGENTS.md) for the codebase conventions — package versions go in `Directory.Packages.props`, tests live next to code, no per-file license headers (the `LICENSE` file at the root is the single source of truth). (AGENTS.md is the canonical brief for both human contributors and AI tools; GitHub Copilot reads it natively and `CLAUDE.md` points to it.) -- The bootstrappers are now thin: `./build.ps1` / `./build.sh` provision .NET if needed, then run `dotnet tool restore` + `dotnet fallout "$@"`. The `Fallout.GlobalTools` version is pinned in `.config/dotnet-tools.json`. +- The bootstrappers are now thin: `./build.ps1` / `./build.sh` provision .NET if needed, then run `dotnet tool restore` + `dotnet fallout "$@"`. The `Fallout.GlobalTool` version is pinned in `.config/dotnet-tools.json`. - Run `./build.ps1 Test` (or `./build.sh Test`, or directly `dotnet fallout Test` once your tools are restored) locally first. ### When writing the PR diff --git a/README.md b/README.md index aaea3c38..46ffa51e 100644 --- a/README.md +++ b/README.md @@ -52,16 +52,16 @@ fallout-migrate ## Install ```sh -dotnet tool install -g Fallout.GlobalTools +dotnet tool install -g Fallout.GlobalTool ``` The CLI installs as `fallout`. Verify with `fallout --help`. > [!NOTE] -> **Upgrading from `Fallout.GlobalTool`?** The dotnet-tool package is now `Fallout.GlobalTools` — same `fallout` command. Uninstall the old one first so you don't end up with two tools claiming the same command: +> **Coming from NUKE's `10.x` tool?** Nothing to do — `Fallout.GlobalTool` is the same package id you already have pinned, so `dotnet tool update` just works. The only exception is the short-lived `Fallout.GlobalTools` (plural) id: if you installed `10.4.0-rc.4` from it, uninstall it and reinstall from `Fallout.GlobalTool` so you don't have two tools claiming the `fallout` command. > > ```sh -> dotnet tool uninstall -g Fallout.GlobalTool +> dotnet tool uninstall -g Fallout.GlobalTools > ``` For per-repo manifest pinning (`.config/dotnet-tools.json`), project setup, and shell completion, see the [Installation guide on docs.fallout.build](https://docs.fallout.build/getting-started/installation). diff --git a/build/Build.cs b/build/Build.cs index 7292dff7..8be5de69 100644 --- a/build/Build.cs +++ b/build/Build.cs @@ -283,8 +283,13 @@ IEnumerable NuGetPackageFiles .DependsOn() .Executes(() => { - SuppressErrors(() => DotNet($"tool uninstall -g {Solution.Fallout_Cli.Name}"), logWarning: false); - DotNet($"tool install -g {Solution.Fallout_Cli.Name} --add-source {OutputDirectory} --version {DefaultDeploymentVersion}"); + // Read the id off the csproj rather than hardcoding it: the tool's PackageId is + // deliberately decoupled from its project/assembly name (Fallout.Cli packs as + // Fallout.GlobalTool), so Solution.Fallout_Cli.Name would install the wrong package. + var packageId = Solution.Fallout_Cli.GetProperty("PackageId"); + + SuppressErrors(() => DotNet($"tool uninstall -g {packageId}"), logWarning: false); + DotNet($"tool install -g {packageId} --add-source {OutputDirectory} --version {DefaultDeploymentVersion}"); }); T From() diff --git a/docs/01-getting-started/01-installation.md b/docs/01-getting-started/01-installation.md index 7d68e16e..b9ee47c6 100644 --- a/docs/01-getting-started/01-installation.md +++ b/docs/01-getting-started/01-installation.md @@ -6,11 +6,11 @@ Before you can set up a build project, you need to install Fallout's dedicated [ ```powershell # terminal-command -dotnet tool install Fallout.GlobalTools --global +dotnet tool install Fallout.GlobalTool --global ``` :::tip -For repos that already have a `.config/dotnet-tools.json` manifest with `Fallout.GlobalTools` pinned (this is what `fallout :setup` creates), you can skip the global install and run `dotnet tool restore` instead — the local manifest version then takes precedence. +For repos that already have a `.config/dotnet-tools.json` manifest with `Fallout.GlobalTool` pinned (this is what `fallout :setup` creates), you can skip the global install and run `dotnet tool restore` instead — the local manifest version then takes precedence. ::: From now on, you can use the global tool to: diff --git a/docs/01-getting-started/02-setup.md b/docs/01-getting-started/02-setup.md index 68c664c3..bda476b6 100644 --- a/docs/01-getting-started/02-setup.md +++ b/docs/01-getting-started/02-setup.md @@ -34,7 +34,7 @@ The setup will create a number of files in your repository and – if you've cho ```bash ├── .config -│ └── dotnet-tools.json # Local tool manifest pinning Fallout.GlobalTools +│ └── dotnet-tools.json # Local tool manifest pinning Fallout.GlobalTool │ ├── .fallout # Root directory marker │ ├── build.schema.json # Build schema file @@ -51,7 +51,7 @@ The setup will create a number of files in your repository and – if you've cho ``` :::note -The two thin bootstrappers (`build.ps1` and `build.sh`) provision the .NET SDK locally when it's not on `PATH`, then run `dotnet tool restore` and `dotnet fallout "$@"`. They're optional once you have a global `dotnet` install and have run `dotnet tool restore` at least once — but they're the safest way to run the build in CI and on a freshly-cloned machine. The `.config/dotnet-tools.json` manifest pins the exact `Fallout.GlobalTools` version your build expects. +The two thin bootstrappers (`build.ps1` and `build.sh`) provision the .NET SDK locally when it's not on `PATH`, then run `dotnet tool restore` and `dotnet fallout "$@"`. They're optional once you have a global `dotnet` install and have run `dotnet tool restore` at least once — but they're the safest way to run the build in CI and on a freshly-cloned machine. The `.config/dotnet-tools.json` manifest pins the exact `Fallout.GlobalTool` version your build expects. ::: ## Project Structure @@ -64,7 +64,7 @@ While you can enjoy writing most build-relevant logic inside your build console ```powershell ├── .config -│ └── dotnet-tools.json # Local tool manifest (Fallout.GlobalTools pin) +│ └── dotnet-tools.json # Local tool manifest (Fallout.GlobalTool pin) │ ├── .fallout │ ├── parameters.json # Parameters files diff --git a/docs/01-getting-started/03-execution.md b/docs/01-getting-started/03-execution.md index 62a5f986..6e6da28c 100644 --- a/docs/01-getting-started/03-execution.md +++ b/docs/01-getting-started/03-execution.md @@ -34,7 +34,7 @@ fallout [arguments] :::info -The bootstrappers are thin: they provision the .NET SDK if it isn't already installed, run `dotnet tool restore` (to pin the `Fallout.GlobalTools` version from `.config/dotnet-tools.json`), then forward to `dotnet fallout`. Once `dotnet` is on your `PATH` and tools are restored, `fallout [arguments]` and `./build.sh [arguments]` do the same thing. +The bootstrappers are thin: they provision the .NET SDK if it isn't already installed, run `dotnet tool restore` (to pin the `Fallout.GlobalTool` version from `.config/dotnet-tools.json`), then forward to `dotnet fallout`. Once `dotnet` is on your `PATH` and tools are restored, `fallout [arguments]` and `./build.sh [arguments]` do the same thing. ::: :::info diff --git a/docs/05-cicd/github-actions.md b/docs/05-cicd/github-actions.md index 2ee44a27..ec80f02e 100644 --- a/docs/05-cicd/github-actions.md +++ b/docs/05-cicd/github-actions.md @@ -98,7 +98,7 @@ jobs: ``` :::info -The generated workflow uses `actions/setup-dotnet` to install the .NET SDK on the runner, then `dotnet tool restore` to install the `Fallout.GlobalTools` version pinned in `.config/dotnet-tools.json`, then `dotnet fallout ` to run your build. Your repository needs a `.config/dotnet-tools.json` manifest with `Fallout.GlobalTools` pinned — `fallout :setup` creates one automatically. +The generated workflow uses `actions/setup-dotnet` to install the .NET SDK on the runner, then `dotnet tool restore` to install the `Fallout.GlobalTool` version pinned in `.config/dotnet-tools.json`, then `dotnet fallout ` to run your build. Your repository needs a `.config/dotnet-tools.json` manifest with `Fallout.GlobalTool` pinned — `fallout :setup` creates one automatically. ::: diff --git a/docs/introduction.md b/docs/introduction.md index 3dcecfe4..8e617b36 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -45,7 +45,7 @@ Get a feeling how your Cake scripts would look like in Fallout. ```powershell # terminal-command -dotnet tool install Fallout.GlobalTools --global +dotnet tool install Fallout.GlobalTool --global ``` **2. Go to a repository built with Cake.** diff --git a/docs/migration/from-globaltool-to-cli.md b/docs/migration/from-globaltool-to-cli.md deleted file mode 100644 index 062f4bb8..00000000 --- a/docs/migration/from-globaltool-to-cli.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: Fallout.GlobalTool → Fallout.Cli -description: Migrating from the renamed Fallout CLI NuGet package. Short guide — the command name didn't change, just the package ID. -draft: true ---- - - - - -In v11, the dotnet-tool NuGet package id was renamed: **`Fallout.GlobalTool` → `Fallout.Cli`**. The **command name stays `fallout`**, so build scripts and shell invocations don't change. The only thing that moves is the install/restore reference. - -> If you've never installed `Fallout.GlobalTool`, you don't need this page — install `Fallout.Cli` directly per the [Install section in the README](https://github.com/Fallout-build/Fallout#install). - -## TL;DR - -**Global install:** - -```sh -dotnet tool uninstall -g Fallout.GlobalTool -dotnet tool install -g Fallout.Cli -``` - -**Local manifest (`.config/dotnet-tools.json`):** open the file, replace the `fallout.globaltool` entry with `fallout.cli`, restore. - -```diff - { - "version": 1, - "isRoot": true, - "tools": { -- "fallout.globaltool": { -+ "fallout.cli": { - "version": "11.0.0", - "commands": [ "fallout" ] - } - } - } -``` - -```sh -dotnet tool restore -``` - -That's it. `fallout :setup`, `fallout Compile`, etc. all work unchanged because the command name (`fallout`) is the same. - -## Why the rename - -`dotnet tool install Fallout.Cli` is easier to type and remember than `dotnet tool install Fallout.GlobalTool`. The "GlobalTool" suffix was a NUKE-era artefact distinguishing the dotnet-tool wrapper from the framework libraries — but every consumer's first encounter with the tool is at install-time, and `Fallout.Cli` is what they reach for naturally. - -The change is purely cosmetic at the NuGet metadata layer. No source-level API changed; the C# namespace inside the tool moved from `Fallout.GlobalTool.*` to `Fallout.Cli.*` but those types are `internal` so external consumers never referenced them. - -## Affected versions - -| Package | Last published | Status | -|---|---|---| -| `Fallout.GlobalTool` | `10.3.40` | Frozen on nuget.org. **Unlisted** as part of the v11 semver cleanup (see [#220](https://github.com/Fallout-build/Fallout/pull/220)). Existing installs keep working; `dotnet tool update` won't find newer versions. | -| `Fallout.Cli` | `11.0.x` (current) | Active. Receives all future tool releases. | - -The `10.3.41` through `10.3.47` patch releases of `Fallout.Cli` are **also unlisted** — they shipped under a patch number that hid breaking changes, fixed by the v11 major bump. Pin to **`11.0.0`** or later. - -## Migration scenarios - -### You installed `Fallout.GlobalTool` globally on your machine - -```sh -dotnet tool uninstall -g Fallout.GlobalTool -dotnet tool install -g Fallout.Cli -``` - -`dotnet tool list -g` confirms only `Fallout.Cli` remains. The `fallout` command on your PATH now resolves to the renamed package. - -### Your repo has a local `.config/dotnet-tools.json` manifest - -Edit the manifest, replace `fallout.globaltool` with `fallout.cli` (both the key and any references). Bump the version pin to the current `Fallout.Cli` release (`11.0.x` and above). - -```sh -dotnet tool restore -``` - -Confirm with `dotnet tool list` — the `fallout.cli` row should appear, the `fallout.globaltool` row should not. - -### Your repo uses the thin `build.sh` / `build.ps1` shims - -Nothing to do. The shims call `dotnet fallout "$@"` — they look up the command by name, not by package ID, and `dotnet tool restore` resolves whatever your manifest pins. - -If your repo is still on the **old fat bootstrappers** (with the `BUILD_PROJECT_FILE` config block + explicit `dotnet build` + `dotnet run --project`), those don't depend on the global tool at all and keep working unchanged. To adopt the new shape, re-run `fallout :setup --force` after upgrading. See [the v11 CHANGELOG entry for #204](https://github.com/Fallout-build/Fallout/blob/main/CHANGELOG.md) for what the new shape looks like. - -### Your repo's CI calls `dotnet fallout` directly (no shim) - -Update the workflow's `dotnet tool restore` step's manifest to reference `fallout.cli`. The actual `dotnet fallout ` lines stay identical. - -## Stuck on 10.3.40 of `Fallout.GlobalTool`? - -The package is unlisted but still downloadable if you have an explicit pin in your manifest. You can keep running on `10.3.40` indefinitely. When you're ready to upgrade, follow the steps above — there is no required intermediate step. `Fallout.GlobalTool 10.3.40` and `Fallout.Cli 11.0.0` are the same code-base; the only consequential difference is the package ID and the semver-correct breaking changes that have accumulated. - -## Refs - -- [#206](https://github.com/Fallout-build/Fallout/pull/206) — the rename PR. -- [#210](https://github.com/Fallout-build/Fallout/pull/210) — README install section + the prompt to uninstall old CLI. -- [#220](https://github.com/Fallout-build/Fallout/pull/220) — the v11 semver-policy bump that catalysed unlisting the 10.3.41-47 range. -- [`from-nuke.md`](from-nuke.md) — if you're also migrating from NUKE, do that first; this guide is downstream of it. diff --git a/docs/rebrand-plan.md b/docs/rebrand-plan.md index 04f9fe9d..f7250a01 100644 --- a/docs/rebrand-plan.md +++ b/docs/rebrand-plan.md @@ -45,7 +45,7 @@ This is locked by the bridge-package design — `[TypeForwardedTo]` requires the | `Nuke.Common.Utilities` (+ `.Collections`, `.Net`) | `Fallout.Common.Utilities` | | | `Nuke.Common.ValueInjection` | `Fallout.Common.ValueInjection` | | | `Nuke.Components` | `Fallout.Components` | | -| `Nuke.GlobalTool` (+ `.Rewriting.Cake`) | `Fallout.Cli` | Project/namespace/assembly is `Fallout.Cli`. The **published package id is `Fallout.GlobalTools`** (`dotnet tool install Fallout.GlobalTools`) — decoupled from the assembly name on purpose. Command name stays `fallout`. | +| `Nuke.GlobalTool` (+ `.Rewriting.Cake`) | `Fallout.Cli` | Project/namespace/assembly is `Fallout.Cli`. The **published package id stays `Fallout.GlobalTool`** (`dotnet tool install Fallout.GlobalTool`) — deliberately decoupled from the assembly name and deliberately *not* renamed, so the existing `10.x` install base never has to migrate. Command name stays `fallout`. | | `Nuke.MSBuildTasks` | `Fallout.MSBuildTasks` | | | `Nuke.SourceGenerators` | `Fallout.SourceGenerators` | | | `Nuke.Utilities.Text.Json` | `Fallout.Utilities.Text.Json` | | diff --git a/src/Fallout.Build/Execution/Extensions/UpdateNotificationAttribute.cs b/src/Fallout.Build/Execution/Extensions/UpdateNotificationAttribute.cs index bbb3c57b..a4da113b 100644 --- a/src/Fallout.Build/Execution/Extensions/UpdateNotificationAttribute.cs +++ b/src/Fallout.Build/Execution/Extensions/UpdateNotificationAttribute.cs @@ -33,9 +33,9 @@ private static void Notify() Host.Warning( new[] { - "--- UPDATE RECOMMENDED FROM 5.1.0 ---", + "--- UPDATE RECOMMENDED ---", "1. Update your global tool", - " dotnet tool update Fallout.GlobalTools -g", + " dotnet tool update Fallout.GlobalTool -g", "2. Update your build", " fallout :update", "3. Confirm on update for configuration file and build scripts", diff --git a/src/Fallout.Cli/BuildScaffolder.cs b/src/Fallout.Cli/BuildScaffolder.cs index ea55d5f5..1f1c79bc 100644 --- a/src/Fallout.Cli/BuildScaffolder.cs +++ b/src/Fallout.Cli/BuildScaffolder.cs @@ -57,10 +57,10 @@ public void WriteBuildScripts( })), platformFamily: PlatformFamily.Windows); - // .config/dotnet-tools.json pins Fallout.GlobalTools as a local tool so the thin shims + // .config/dotnet-tools.json pins Fallout.GlobalTool as a local tool so the thin shims // (build.sh / build.ps1) can `dotnet tool restore` and `dotnet fallout` deterministically. // Skip if the consumer already has a manifest — they may have other tools pinned and we - // don't want to clobber. They can add the `fallout.globaltools` entry manually. + // don't want to clobber. They can add the `fallout.globaltool` entry manually. var toolManifest = rootDirectory / ".config" / "dotnet-tools.json"; if (!toolManifest.FileExists()) { diff --git a/src/Fallout.Cli/Fallout.Cli.csproj b/src/Fallout.Cli/Fallout.Cli.csproj index 60071de7..e54e0ad8 100644 --- a/src/Fallout.Cli/Fallout.Cli.csproj +++ b/src/Fallout.Cli/Fallout.Cli.csproj @@ -6,9 +6,12 @@ LatestMajor true fallout - - Fallout.GlobalTools + + Fallout.GlobalTool diff --git a/src/Fallout.Cli/templates/dotnet-tools.json b/src/Fallout.Cli/templates/dotnet-tools.json index f44331ec..a4c273db 100644 --- a/src/Fallout.Cli/templates/dotnet-tools.json +++ b/src/Fallout.Cli/templates/dotnet-tools.json @@ -2,7 +2,7 @@ "version": 1, "isRoot": true, "tools": { - "fallout.globaltools": { + "fallout.globaltool": { "version": "_FALLOUT_CLI_VERSION_", "commands": [ "fallout"