Use latest LabAPI version; rename SkipGit param

This commit is contained in:
2026-08-27 00:14:12 +02:00
parent 45eefc7765
commit 8ac9e21714
3 changed files with 23 additions and 21 deletions
+18 -10
View File
@@ -13,18 +13,15 @@ are ordinary project files at that point, not template scaffolding.
## Repo is template *source* — read before touching any file
`.template.config/template.json` sets this folder's name as the template's
`sourceName` and defines two text-replacement `symbols` (plus `skipRestore` and
`skipGit`, which only toggle post-generation actions and replace no text). The
dotnet templating engine does a literal, repo-wide **string replacement** at
generation time — not semantic renaming — driven by that config:
`sourceName` and defines one text-replacement `symbol`, `PluginAuthor` (plus
`skipRestore` and `SkipGit`, which only toggle post-generation actions and replace no
text). The dotnet templating engine does a literal, repo-wide **string replacement**
at generation time — not semantic renaming — driven by that config:
- The folder/project name (`sourceName` in `template.json`, currently this repo's own
folder name) → whatever `-n`/`--name` the consumer passes to `dotnet new`.
- The placeholder value of the `PluginAuthor` symbol (the string currently sitting in
`EntryPoint.cs`'s `Author` property) → the consumer's `--PluginAuthor`.
- The placeholder value of the `LabApiVersion` symbol (the version string currently in
the `.csproj`'s `PackageReference` and in `EntryPoint.cs`'s `RequiredApiVersion`) →
the consumer's `--LabApiVersion`.
Open `template.json` to see the exact current literal for each — don't hardcode them
again here or anywhere else in prose, because this file itself ships inside every
@@ -32,7 +29,7 @@ generated project and any exact match gets rewritten too (self-referential text
"the project is called X" would silently turn into nonsense after generation).
Consequences:
- Never introduce an exact match of one of those three literals elsewhere in the repo
- Never introduce an exact match of one of those two literals elsewhere in the repo
unless you intend it to be substituted too.
- If you add a new thing that should be configurable at generation time, add a symbol
to `template.json` (`type: parameter`, `replaces: "<literal>"`) instead of
@@ -45,7 +42,7 @@ Consequences:
## Repo layout (only what affects decisions)
- `.template.config/template.json` — template identity, the symbols above plus
`skipGit` (a display-only toggle, see below), `primaryOutputs` (points at the
`SkipGit` (a display-only toggle, see below), `primaryOutputs` (points at the
project file using its pre-substitution literal name — that's correct and expected,
not a bug), and two `postActions`: the standard dotnet-templating "restore NuGet
packages" action (id `210D431B-...`; skipped in Visual Studio, which restores on
@@ -80,7 +77,7 @@ This was a deliberate choice after testing the alternative:
- Visual Studio's own "New Project" dialog already has a built-in "Create new Git
repository" checkbox that works for any template, including this one, with zero
template-side configuration — so VS users get this for free regardless.
- CLI users see the printed reminder above (governed by the `skipGit` symbol) and run
- CLI users see the printed reminder above (governed by the `SkipGit` symbol) and run
the one-liner themselves.
## LabAPI contract (verified against northwood-studios/LabAPI source, not guessed)
@@ -119,6 +116,17 @@ assume one exists.
`MSB3270` (via `ResolveAssemblyWarnOrErrorOnTargetArchitectureMismatch=None`). Don't
broaden either into a blanket suppression and don't remove them without
understanding why (comments sit next to both in the `.csproj`).
- The `Northwood.LabAPI` `PackageReference` uses a floating `Version="*"` on purpose,
so every `dotnet restore` always pulls whatever is the latest stable release on
NuGet at that moment — there's no version to bump here. This is intentionally
**not** wired to `EntryPoint.cs`'s `RequiredApiVersion`, which can't be a floating
value (`System.Version` has no such concept and would throw at runtime if it tried).
`RequiredApiVersion` is a separate, manually-maintained literal representing the
minimum LabAPI version the scaffolded code is known to work with — bump it by hand
if you verify compatibility with a newer release, don't try to auto-sync it with the
floating restore. Also be aware a floating version means a plugin generated today can
restore a different (newer) LabAPI release than one generated last week, with no
pinning — that's the deliberate trade-off of "always latest" over reproducibility.
## Code style for anything you write here