Install the kit into .mskit/ and move .toolkit/ installs

.github/workflows/ci.yml

@@ -47,6 +47,8 @@ jobs:
           sh -n tests/manager.sh
           sh -n tests/nuget-isolation.sh
           sh -n tests/nuget-isolation.test.sh
+          sh -n tests/update-dir.test.sh
+          sh -n tests/update-self.sh
 
       - name: Pack the kit
         shell: bash

CHANGELOG.md

@@ -6,12 +6,14 @@ All notable changes to this project are documented here. The format follows [Kee
 
 ### Breaking changes
 
+- The kit's default folder is `.mskit/` instead of `.toolkit/`: a fresh install writes `.mskit/`, and `Directory.Build.props` / `.targets` import `.mskit/msbuild/init.props` / `init.targets`. `update.sh --kit-dir NAME` (`update.ps1 -KitDir NAME`) picks another folder name, and `kit.json` records it as `kitDir`, so later runs find it. A run that finds an older `.toolkit/` install moves it to the kit folder (`git mv` when it is tracked) and rewrites `.toolkit` in `Directory.Build.props`, `Directory.Build.targets`, `.gitignore` and `.github/dependabot.yml`; it stops when both folders exist, and `--dry-run` shows the move and changes nothing. **From 0.2.1 the upgrade takes two runs:** 0.2.1's `update.sh` installs the new version into `.toolkit/` and copies the new script, which moves the folder when you run it again (`sh .toolkit/update.sh`). Keep `.toolkit/` with `--kit-dir .toolkit`. The release zip keeps its `.toolkit/` layout so that 0.2.1's script can install it. See [Moving from `.toolkit/`](./docs/install-and-update.md#moving-from-toolkit).
 - Warning and error codes drop the underscore after the prefix: `MSKITVER006`, `MSKITPKG015`, and so on, with the same family and number. `NoWarn`, `WarningsAsErrors`, `WarningsNotAsErrors` and `MSKit_SkipPackageChecks` entries that name a code the old way no longer match: rename them. Each section of the [code reference](./docs/reference/codes.md) names the code's former spelling.
 
 ### Added
 
 - Every warning and error links to its section of the [code reference](./docs/reference/codes.md) (`HelpLink`, shown by the terminal logger and IDEs). `MSKit_CodesHelpBaseUrl` points the links at another copy of the page.
 - A machine-readable catalog of the codes: every part declares each code it reports as a `BuildDiagnosticDescriptor` item (`Title`, `MessageFormat`, `Description`, `Category`, `DefaultSeverity`, `HelpLink`) in its own `diagnostic.descriptors.props`, so a tool can read them with `dotnet msbuild -getItem:BuildDiagnosticDescriptor` and tell the owning part from the item's `DefiningProjectFullPath`. Each section of the [code reference](./docs/reference/codes.md) now opens with the code's title. See the [diagnostic catalog](./docs/reference/diagnostic-catalog.md).
+- `MSKit_KitDirName`: the kit folder's name. The `MSKITROSLYN001`..`003` messages name the update scripts with it, so they show the folder the kit is installed in.
 - `MSKit_DefaultPackageIconUrl`: when the kit packs its own icon, this URL is also written as `PackageIconUrl`, so clients that predate embedded icons show it; nuget.org keeps showing the embedded one. Empty by default; an owner sets it in its owner layer. `MSKITPKG008` now reports only a `PackageIconUrl` the project sets itself. See [docs/packaging.md](./docs/packaging.md#package-metadata).
 - `manager/`: the first build of `mskit-manager`, the `DragoAnt.MSBuildKit.Manager` .NET tool (`net8.0`, `net10.0`, `RollForward=Major`) that will install, update and migrate the kit. This build has one command, `status [--json]`, which prints the tool version; the logo goes to stderr, only on a terminal and never with `--no-logo`, so `--json` output always parses. Each run writes a log under `<system temp>/mskit-manager/logs/`, named after the command, newest 20 kept. Not published yet.
 - `manager/`: the package model behind the coming `install` — readers for `mskit.package.json`, the trunk's `catalog.json` and a company or team `filter.json`; the part selection (core defaults, then the company filter, the team filter and the repository's `kit.json`, a later layer winning per part, with required and company-locked parts refused and `requires` closed); `kit.json` schema 2, which also reads the schema 1 that `update.sh` writes and keeps a `parts` array spread over several lines; and the install manifest. No command uses them yet.

CONTRIBUTING.md

@@ -4,9 +4,9 @@ Issues and pull requests are welcome.
 
 ## Layout
 
-- `kit/.toolkit/` is exactly what a release zip contains and what `update.sh` / `update.ps1` install: `msbuild/` (one folder per part plus the `init.props` / `init.targets` entry points), `res/`, `kit.parts` and the update scripts.
-- `samples/MinimalLibrary` is a consumer with a library and a test project; its `.toolkit/` is installed by the self-test and not committed.
-- `tests/run.sh` is the self-test; `tests/fixtures/PackageChecks` breaks every package rule on purpose. `tests/manager.sh` builds, tests, packs and installs the tool.
+- `kit/.toolkit/` is exactly what a release zip contains (under `.toolkit/`, the layout the 0.2.1 updater reads) and what `update.sh` / `update.ps1` install into a consumer's kit folder, `.mskit/` by default: `msbuild/` (one folder per part plus the `init.props` / `init.targets` entry points), `res/`, `kit.parts` and the update scripts.
+- `samples/MinimalLibrary` is a consumer with a library and a test project; its `.mskit/` is installed by the self-test, starting from a v0.2.1 `.toolkit/` install that the new `update.sh` moves, and not committed. `tests/fixtures/TfmConstants` keeps its kit in `.toolkit/` through `--kit-dir`, so a non-default folder builds too.
+- `tests/run.sh` is the self-test; `tests/fixtures/PackageChecks` breaks every package rule on purpose. `tests/update-dir.test.sh` checks the kit folder of both update scripts (fresh install, `--kit-dir`, the move from `.toolkit/`, the two-run upgrade from the real v0.2.1 scripts) without `dotnet`. `tests/manager.sh` builds, tests, packs and installs the tool.
 - `tools/pack-kit.sh` builds the release zip and its SHA-256.
 - `manager/` is the `mskit-manager` .NET tool: its own solution, central package versions and `global.json`, built against `manager/.toolkit/` — the working-tree kit installed with `sh kit/.toolkit/update.sh --source kit --root manager` and committed.
 - `docs/` holds the user documentation, read in the order of [docs/README.md](./docs/README.md); `docs/reference/` lists every property and code. `tools/docs-check.sh` keeps them honest against the kit.
@@ -55,7 +55,7 @@ Both scripts restore into folders of their own and share third-party packages be
 - `sh tools/docs-check.sh` fails on a property, item or code without its reference entry, on a name the docs mention that the kit lacks, and on a broken relative link; `--list properties|items|codes` prints the kit's inventory with the file and line of each.
 - The README stays short: key features, install, links. Detail goes to the topic page in `docs/`.
 - A new part needs a line in `kit/.toolkit/kit.parts` and its `init.props` / `init.targets` imports in the entry points.
-- Keep scripts POSIX `sh` and PowerShell 7 equivalent; `update.sh` and `update.ps1` must produce the same `.toolkit/`.
+- Keep scripts POSIX `sh` and PowerShell 7 equivalent; `update.sh` and `update.ps1` must produce the same kit folder.
 - A test that restores a package built in this repository runs from `tests/run.sh` or `tests/manager.sh`, which keep it out of the machine's global-packages folder and out of the shared folder.
 - Add a line to `CHANGELOG.md` under `Unreleased`.
 

README.md

@@ -13,7 +13,7 @@ Shared MSBuild settings for .NET repositories that publish NuGet packages: nuget
 - **Versions from release tags.** Tag `v1.4.0` and the packages are `1.4.0`; branch builds are `1.4.0-ci.<run>`, pull requests `1.4.0-pr.<n>.<run>`, local builds `9999.0.0`. [Versioning](./docs/versioning.md)
 - **Tests on Microsoft.Testing.Platform v2.** Projects named `*.Tests` become [xUnit v3](https://xunit.net/docs/getting-started/v3/microsoft-testing-platform) test projects with coverage, TRX and JUnit reports, an assertion library and [NSubstitute](https://nsubstitute.github.io/). [Testing](./docs/testing.md)
 - **Build checks that keep a repository consistent.** Target frameworks declared once, banned packages, prerelease dependencies on a stable branch, `TreatWarningsAsErrors` drift. [Build defaults and checks](./docs/build.md)
-- **Plain files, one update script.** The kit lives in your repository's `.toolkit/` folder, so every change shows up in a pull request; `update.sh` / `update.ps1` install a release after checking its SHA-256. It is not a NuGet package or an MSBuild SDK: nothing is restored at build time. [Install and update](./docs/install-and-update.md)
+- **Plain files, one update script.** The kit lives in your repository's `.mskit/` folder, so every change shows up in a pull request; `update.sh` / `update.ps1` install a release after checking its SHA-256. It is not a NuGet package or an MSBuild SDK: nothing is restored at build time. [Install and update](./docs/install-and-update.md)
 
 ## Install
 
@@ -29,7 +29,7 @@ Invoke-WebRequest https://github.com/DragoAnt/MSBuildKit/releases/latest/downloa
 pwsh ./update.ps1; Remove-Item update.ps1
 ```
 
-Then declare the next version in `Directory.Version.props` and commit `.toolkit/`. [Getting started](./docs/getting-started.md) walks through the first build, test and pack; [`samples/MinimalLibrary`](./samples/MinimalLibrary) is a complete repository with every check passing.
+Then declare the next version in `Directory.Version.props` and commit `.mskit/`. [Getting started](./docs/getting-started.md) walks through the first build, test and pack; [`samples/MinimalLibrary`](./samples/MinimalLibrary) is a complete repository with every check passing.
 
 ## Documentation
 

docs/build.md

@@ -35,10 +35,11 @@ Set `MSKit_IsDevEnv` yourself to build "as CI" locally (`-p:MSKit_IsDevEnv=False
 
 | Property | Value |
 | --- | --- |
-| `MSKit_SlnFileDirectory` | the folder of the `.slnx` being built (`SlnxFilePath`), else the folder that holds `.toolkit/`; ends with `/` |
+| `MSKit_SlnFileDirectory` | the folder of the `.slnx` being built (`SlnxFilePath`), else the folder that holds `.mskit/`; ends with `/` |
 | `MSKit_SlnFileName` | the solution name without extension, when building a `.slnx` |
 | `MSKit_GitRoot` | the nearest folder above the project with a `.git` (worktrees included) |
-| `MSKit_ToolkitDir`, `MSKit_ToolkitMSBuildDir` | `.toolkit/` and `.toolkit/msbuild/`, absolute, ending with `/` |
+| `MSKit_ToolkitDir`, `MSKit_ToolkitMSBuildDir` | the kit folder (`.mskit/` by default) and its `msbuild/`, absolute, ending with `/` |
+| `MSKit_KitDirName` | the kit folder's name, such as `.mskit` |
 | `MSKit_ProjectObjDir` | the project's `obj` folder, absolute |
 | `MSKit_Branch` | on GitHub Actions `GITHUB_HEAD_REF` (pull requests) or `GITHUB_REF_NAME`; else read from `.git/HEAD`; else `unknown-branch` |
 | `MSKit_IsStableBranch` | `true` when `MSKit_Branch` matches `MSKit_IsStableBranchRegex` (case-insensitive): the owner layer's `^(main\|release/.+)$`, the kit's own default `^(main\|master\|release/.+)$` |

docs/customizing.md

@@ -1,6 +1,6 @@
 # Customizing
 
-Three ways to change what the kit does without editing `.toolkit/msbuild/` (an update overwrites it): set a property, add one of the extension files the kit looks for, or hook your own file in around the kit. To use the kit for another owner, change the owner layer.
+Three ways to change what the kit does without editing `.mskit/msbuild/` (an update overwrites it): set a property, add one of the extension files the kit looks for, or hook your own file in around the kit. To use the kit for another owner, change the owner layer.
 
 ## Overriding a default
 
@@ -15,13 +15,13 @@ Almost every default is written as `<X Condition="'$(X)'==''">`, so the first va
 
 ## The owner layer
 
-`.toolkit/msbuild/init.company.props` is loaded before every part and holds the owner's defaults; `init.company.targets` is its targets-phase twin (empty for DragoAnt).
+`.mskit/msbuild/init.company.props` is loaded before every part and holds the owner's defaults; `init.company.targets` is its targets-phase twin (empty for DragoAnt).
 
 | Setting | DragoAnt value | Note |
 | --- | --- | --- |
 | `ManufacturerName`, `FullManufacturerName` | `DragoAnt` | **unconditional**: set them below the kit import to change them; they feed `Authors`, `Company`, `Copyright` |
 | `PackageLicenseExpression` | `MIT`, unless `PackageLicenseFile` is set | |
-| `PackageIconPath` | `.toolkit/res/package.icon.png` | |
+| `PackageIconPath` | `.mskit/res/package.icon.png` | |
 | `MSKit_DefaultPackageIconUrl` | not set | another owner sets it here to a hosted copy of its icon, so older clients show it too ([Packaging](./packaging.md#package-metadata)) |
 | `MSKit_PrereleasePackagePrefix` | `DragoAnt.` | [prerelease check](./build.md#reference-checks) |
 | `MSKit_IsStableBranchRegex` | `^(main\|release/.+)$` | |
@@ -61,7 +61,7 @@ Name your own files in `Directory.Build.props` above the kit import; each is imp
 <PropertyGroup>
   <MSKit_AfterInitTargets>$(MSBuildThisFileDirectory)build/after-kit.targets</MSKit_AfterInitTargets>
 </PropertyGroup>
-<Import Project="$(MSBuildThisFileDirectory).toolkit/msbuild/init.props" />
+<Import Project="$(MSBuildThisFileDirectory).mskit/msbuild/init.props" />
 ```
 
 `MSKit_BeforeInitTargets` and `MSKit_AfterInitTargets` are read in the targets phase, so they can also be set in the csproj.

docs/getting-started.md

@@ -20,22 +20,22 @@ The script downloads the latest release, checks its SHA-256, and writes:
 
 | Path | What |
 | --- | --- |
-| `.toolkit/msbuild/` | the kit: one folder per [part](./parts.md) and the `init.props` / `init.targets` entry points |
-| `.toolkit/res/package.icon.png` | the package icon |
-| `.toolkit/kit.json` | the pinned version, its SHA-256 and your optional parts |
-| `.toolkit/kit.parts`, `.toolkit/update.sh`, `.toolkit/update.ps1` | the part list and the update scripts |
+| `.mskit/msbuild/` | the kit: one folder per [part](./parts.md) and the `init.props` / `init.targets` entry points |
+| `.mskit/res/package.icon.png` | the package icon |
+| `.mskit/kit.json` | the pinned version, its SHA-256 and your optional parts |
+| `.mskit/kit.parts`, `.mskit/update.sh`, `.mskit/update.ps1` | the part list and the update scripts |
 | `Directory.Build.props`, `Directory.Build.targets` | only when missing: one import each |
 
 If the two `Directory.Build.*` files already exist, the script prints the line each needs instead of editing them:
 
 ```xml
 <!-- Directory.Build.props -->
-<Import Project="$(MSBuildThisFileDirectory).toolkit/msbuild/init.props" />
+<Import Project="$(MSBuildThisFileDirectory).mskit/msbuild/init.props" />
 <!-- Directory.Build.targets -->
-<Import Project="$(MSBuildThisFileDirectory).toolkit/msbuild/init.targets" />
+<Import Project="$(MSBuildThisFileDirectory).mskit/msbuild/init.targets" />
 ```
 
-Commit `.toolkit/` with the rest of the repository: the kit is reviewed like any other change. [Install and update](./install-and-update.md) has every option.
+Commit `.mskit/` with the rest of the repository: the kit is reviewed like any other change. To use another folder name, pass `--kit-dir <name>` (`-KitDir`); an older `.toolkit/` install moves on its own. [Install and update](./install-and-update.md) has every option.
 
 ## 2 Declare the next version