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/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/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 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 @@ + + + + +