From 0d97daeaf387b7db89f5c8b93978512a89b3ddf9 Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Sat, 30 May 2026 18:30:51 +0100 Subject: [PATCH 1/2] Improve NuGet package metadata, README and Source Link Add RepositoryUrl/RepositoryType/PackageProjectUrl, pack the root README via PackageReadmeFile, and reference Microsoft.SourceLink.GitHub for the WLED and WLED.DependencyInjection packages so nuget.org links back to the repo, renders the README, and ships working Source Link. Adds plans/15-nuget-package-metadata.md and updates the roadmap and changelog. --- CHANGELOG.md | 4 + Directory.Build.props | 3 + plans/15-nuget-package-metadata.md | 98 +++++++++++++++++++ plans/README.md | 4 + .../Kevsoft.WLED.DependencyInjection.csproj | 6 ++ src/Kevsoft.WLED/Kevsoft.WLED.csproj | 6 ++ 6 files changed, 121 insertions(+) create mode 100644 plans/15-nuget-package-metadata.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 448bdc6..c67f1e3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -53,6 +53,10 @@ rather than deprecated, so consuming code must be updated. on modern runtimes, so a long-lived client picks up DNS/IP changes instead of pinning a stale connection (fixes [#8](https://github.com/kevbite/WLED.NET/issues/8)). The `netstandard2.0` build falls back to `HttpClientHandler`; use `IHttpClientFactory`/DI there. +- **Richer NuGet package metadata** for `WLED` and `WLED.DependencyInjection`: the package + pages now link back to the GitHub repository (`RepositoryUrl`/`PackageProjectUrl`), render the + README (`PackageReadmeFile`), and ship Source Link (`Microsoft.SourceLink.GitHub`) so + consumers can step through the library source in their debugger. ### Added diff --git a/Directory.Build.props b/Directory.Build.props index f21f371..c22a6f7 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -3,6 +3,9 @@ WLED.NET Copyright 2020 Kevsoft Kevin Smith + https://github.com/kevbite/WLED.NET + git + https://github.com/kevbite/WLED.NET latest netstandard2.0;net8.0;net9.0;net10.0 net8.0;net9.0;net10.0 diff --git a/plans/15-nuget-package-metadata.md b/plans/15-nuget-package-metadata.md new file mode 100644 index 0000000..db150a2 --- /dev/null +++ b/plans/15-nuget-package-metadata.md @@ -0,0 +1,98 @@ +# Plan 15 — NuGet package metadata, README & Source Link + +**Theme:** Packaging · Discoverability · Quality + +Inspired by [a metadata-completeness issue on Mongo.SignalR.Backplane](https://github.com/gottscj/Mongo.SignalR.Backplane/issues/5): +the same class of gaps applies to the `WLED` and `WLED.DependencyInjection` packages. + +## Why + +A NuGet package is a product page. When key metadata is missing, consumers lose trust and +tooling loses links: + +- no **Source repository** link back to GitHub, +- no **Project website** link, +- no **README** rendered on the package page (NuGet renders `PackageReadmeFile`), +- and — for a great debugging experience — **Source Link** lets consumers step into the + library's source straight from their debugger. + +The two packable projects (`src/Kevsoft.WLED`, `src/Kevsoft.WLED.DependencyInjection`) +already set `IncludeSymbols`/`SymbolPackageFormat=snupkg`, `PublishRepositoryUrl`, +`EmbedUntrackedSources` and `PackageLicenseExpression=MIT`, but are missing the repository +URL, project URL, README packaging and the Source Link package — so the symbols/source +experience is incomplete and the package pages have no GitHub/README links. + +## Current state (per `.csproj`) + +Present: `PackageId`, `Title`, `PackageTags`, `PackageIcon`, `PackageLicenseExpression`, +`Description`, `IsPackable`, `EmbedUntrackedSources`, `IncludeSymbols`, +`SymbolPackageFormat=snupkg`, `PublishRepositoryUrl`. `Authors`/`Copyright`/`Product` come +from `Directory.Build.props`. + +Missing: + +- ❌ `RepositoryUrl` / `RepositoryType` → no "Source repository" link. +- ❌ `PackageProjectUrl` → no "Project website" link. +- ❌ `PackageReadmeFile` + packed `README.md` → README not rendered on nuget.org. +- ❌ `Microsoft.SourceLink.GitHub` → Source Link not wired up, so the published `.snupkg` + can't map back to GitHub source. + +## Approach + +Shared identity goes in `Directory.Build.props` (applies to every project; harmless on the +non-packable test/sample projects and keeps the two packages consistent): + +```xml +https://github.com/kevbite/WLED.NET +git +https://github.com/kevbite/WLED.NET +``` + +Per packable project (`Kevsoft.WLED.csproj`, `Kevsoft.WLED.DependencyInjection.csproj`): + +```xml +README.md +... + + + + + + +``` + +Notes / decisions: + +- The repo root `README.md` is reused for both packages. It's the project shop window and is + already kept current as part of every plan's Definition of Done. +- `Microsoft.SourceLink.GitHub` is added per packable project (not globally) so the + build-time package isn't pulled into the test/sample restores. `PrivateAssets="All"` keeps + it out of the consumer's dependency graph. +- `8.0.0` is the current stable Source Link package and supports all four target frameworks + (incl. `netstandard2.0`). +- `EmbedUntrackedSources` + `PublishRepositoryUrl` are already set, so once Source Link is + referenced the deterministic source mapping completes with no further config. + +## Tests + +This is a packaging change with no runtime surface, so there are no new unit tests. Verify by +**packing** instead: + +- `dotnet pack src/Kevsoft.WLED/Kevsoft.WLED.csproj -c Release` produces both a `.nupkg` and a + `.snupkg`. +- Inspect the generated `.nuspec` inside the `.nupkg` and confirm ``, + ``, `README.md` and a packed `README.md` are present. +- Full `dotnet build`/`dotnet test` (all four TFMs) remain green. + +## Definition of Done (per `plans/README.md`) + +1. **README.md** — no consumer-facing API change; the README itself now ships in the package. + No snippet change required. +2. **samples/BasicConsole** — unaffected. +3. **CHANGELOG.md** — record the packaging improvements under the unreleased section. + +## Out of scope + +- Changing the package icon, license file form (`PackageLicenseExpression=MIT` stays), or + versioning scheme. +- Publishing/CI changes — the existing pipeline already pushes `.nupkg`/`.snupkg`. diff --git a/plans/README.md b/plans/README.md index d9617a9..6ab40ba 100644 --- a/plans/README.md +++ b/plans/README.md @@ -64,6 +64,10 @@ These plans cross-reference two mature community libraries (linked by the WLED d | 9 | [Effect metadata (`/json/fxdata`)](9-effect-metadata.md) | Feature | | 10 | [Configuration API (`/json/cfg`)](10-config-api.md) | Feature | | 11 | [Client ergonomics & cross-cutting concerns](11-client-ergonomics-and-cross-cutting.md) | Quality | +| 12 | [Usability & correctness improvements](12-usability-and-correctness-improvements.md) | Quality | +| 13 | [Device ergonomics & agent guidance](13-device-ergonomics-and-agent-guidance.md) | Quality | +| 14 | [HttpClient connection lifetime & DNS staleness](14-httpclient-connection-lifetime.md) | Reliability | +| 15 | [NuGet package metadata, README & Source Link](15-nuget-package-metadata.md) | Packaging | | 12 | [Usability & correctness improvements (post-review)](12-usability-and-correctness-improvements.md) | Correctness | | 13 | [Device ergonomics, catalogs & agent guidance](13-device-ergonomics-and-agent-guidance.md) | Usability | | 14 | [HttpClient connection lifetime & DNS staleness](14-httpclient-connection-lifetime.md) | Correctness | diff --git a/src/Kevsoft.WLED.DependencyInjection/Kevsoft.WLED.DependencyInjection.csproj b/src/Kevsoft.WLED.DependencyInjection/Kevsoft.WLED.DependencyInjection.csproj index 0ecfff6..5e3f787 100644 --- a/src/Kevsoft.WLED.DependencyInjection/Kevsoft.WLED.DependencyInjection.csproj +++ b/src/Kevsoft.WLED.DependencyInjection/Kevsoft.WLED.DependencyInjection.csproj @@ -10,6 +10,7 @@ WLED.NET Dependency Injection WLED;DependencyInjection;IHttpClientFactory icon.png + README.md MIT Microsoft.Extensions.DependencyInjection integration for WLED.NET. True @@ -21,6 +22,11 @@ + + + + + diff --git a/src/Kevsoft.WLED/Kevsoft.WLED.csproj b/src/Kevsoft.WLED/Kevsoft.WLED.csproj index 8d7edcf..ea319c7 100644 --- a/src/Kevsoft.WLED/Kevsoft.WLED.csproj +++ b/src/Kevsoft.WLED/Kevsoft.WLED.csproj @@ -9,6 +9,7 @@ WLED.NET WLED icon.png + README.md MIT A .NET Wrapper around the WLED JSON API. True @@ -20,12 +21,17 @@ + + + + + From 53f406f715e8e19c66854515fdf8640ecee50256 Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Sat, 30 May 2026 18:36:18 +0100 Subject: [PATCH 2/2] Fix Docker pack: copy README and .git for packaging and Source Link The pack stage failed with NU5019 (File not found: '/README.md') because the new PackageReadmeFile content was never copied into the build context. Copy README.md alongside icon.png. Also copy ./.git (and stop ignoring it) so Microsoft.SourceLink.GitHub can resolve the commit and emit real source link information instead of warning that source control information is unavailable. --- .dockerignore | 3 +-- Dockerfile | 2 ++ 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.dockerignore b/.dockerignore index a7b2baf..2141ccf 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,5 +1,4 @@ **/bin **/obj **/.vscode -**/.vs -.git \ No newline at end of file +**/.vs \ No newline at end of file diff --git a/Dockerfile b/Dockerfile index d45d497..5f44ce7 100644 --- a/Dockerfile +++ b/Dockerfile @@ -13,7 +13,9 @@ RUN dotnet restore FROM restore AS build ARG VERSION +COPY ./.git ./.git COPY ./icon.png . +COPY ./README.md . COPY ./src/Kevsoft.WLED/ ./src/Kevsoft.WLED/ COPY ./src/Kevsoft.WLED.DependencyInjection/ ./src/Kevsoft.WLED.DependencyInjection/ RUN dotnet build ./src/Kevsoft.WLED.DependencyInjection/Kevsoft.WLED.DependencyInjection.csproj --configuration Release -p:Version=${VERSION} --no-restore