|
| 1 | +# Plan 15 — NuGet package metadata, README & Source Link |
| 2 | + |
| 3 | +**Theme:** Packaging · Discoverability · Quality |
| 4 | + |
| 5 | +Inspired by [a metadata-completeness issue on Mongo.SignalR.Backplane](https://github.com/gottscj/Mongo.SignalR.Backplane/issues/5): |
| 6 | +the same class of gaps applies to the `WLED` and `WLED.DependencyInjection` packages. |
| 7 | + |
| 8 | +## Why |
| 9 | + |
| 10 | +A NuGet package is a product page. When key metadata is missing, consumers lose trust and |
| 11 | +tooling loses links: |
| 12 | + |
| 13 | +- no **Source repository** link back to GitHub, |
| 14 | +- no **Project website** link, |
| 15 | +- no **README** rendered on the package page (NuGet renders `PackageReadmeFile`), |
| 16 | +- and — for a great debugging experience — **Source Link** lets consumers step into the |
| 17 | + library's source straight from their debugger. |
| 18 | + |
| 19 | +The two packable projects (`src/Kevsoft.WLED`, `src/Kevsoft.WLED.DependencyInjection`) |
| 20 | +already set `IncludeSymbols`/`SymbolPackageFormat=snupkg`, `PublishRepositoryUrl`, |
| 21 | +`EmbedUntrackedSources` and `PackageLicenseExpression=MIT`, but are missing the repository |
| 22 | +URL, project URL, README packaging and the Source Link package — so the symbols/source |
| 23 | +experience is incomplete and the package pages have no GitHub/README links. |
| 24 | + |
| 25 | +## Current state (per `.csproj`) |
| 26 | + |
| 27 | +Present: `PackageId`, `Title`, `PackageTags`, `PackageIcon`, `PackageLicenseExpression`, |
| 28 | +`Description`, `IsPackable`, `EmbedUntrackedSources`, `IncludeSymbols`, |
| 29 | +`SymbolPackageFormat=snupkg`, `PublishRepositoryUrl`. `Authors`/`Copyright`/`Product` come |
| 30 | +from `Directory.Build.props`. |
| 31 | + |
| 32 | +Missing: |
| 33 | + |
| 34 | +- ❌ `RepositoryUrl` / `RepositoryType` → no "Source repository" link. |
| 35 | +- ❌ `PackageProjectUrl` → no "Project website" link. |
| 36 | +- ❌ `PackageReadmeFile` + packed `README.md` → README not rendered on nuget.org. |
| 37 | +- ❌ `Microsoft.SourceLink.GitHub` → Source Link not wired up, so the published `.snupkg` |
| 38 | + can't map back to GitHub source. |
| 39 | + |
| 40 | +## Approach |
| 41 | + |
| 42 | +Shared identity goes in `Directory.Build.props` (applies to every project; harmless on the |
| 43 | +non-packable test/sample projects and keeps the two packages consistent): |
| 44 | + |
| 45 | +```xml |
| 46 | +<RepositoryUrl>https://github.com/kevbite/WLED.NET</RepositoryUrl> |
| 47 | +<RepositoryType>git</RepositoryType> |
| 48 | +<PackageProjectUrl>https://github.com/kevbite/WLED.NET</PackageProjectUrl> |
| 49 | +``` |
| 50 | + |
| 51 | +Per packable project (`Kevsoft.WLED.csproj`, `Kevsoft.WLED.DependencyInjection.csproj`): |
| 52 | + |
| 53 | +```xml |
| 54 | +<PackageReadmeFile>README.md</PackageReadmeFile> |
| 55 | +... |
| 56 | +<ItemGroup> |
| 57 | + <None Include="../../README.md" Pack="true" Visible="false" PackagePath="" /> |
| 58 | +</ItemGroup> |
| 59 | +<ItemGroup> |
| 60 | + <PackageReference Include="Microsoft.SourceLink.GitHub" Version="8.0.0" PrivateAssets="All" /> |
| 61 | +</ItemGroup> |
| 62 | +``` |
| 63 | + |
| 64 | +Notes / decisions: |
| 65 | + |
| 66 | +- The repo root `README.md` is reused for both packages. It's the project shop window and is |
| 67 | + already kept current as part of every plan's Definition of Done. |
| 68 | +- `Microsoft.SourceLink.GitHub` is added per packable project (not globally) so the |
| 69 | + build-time package isn't pulled into the test/sample restores. `PrivateAssets="All"` keeps |
| 70 | + it out of the consumer's dependency graph. |
| 71 | +- `8.0.0` is the current stable Source Link package and supports all four target frameworks |
| 72 | + (incl. `netstandard2.0`). |
| 73 | +- `EmbedUntrackedSources` + `PublishRepositoryUrl` are already set, so once Source Link is |
| 74 | + referenced the deterministic source mapping completes with no further config. |
| 75 | + |
| 76 | +## Tests |
| 77 | + |
| 78 | +This is a packaging change with no runtime surface, so there are no new unit tests. Verify by |
| 79 | +**packing** instead: |
| 80 | + |
| 81 | +- `dotnet pack src/Kevsoft.WLED/Kevsoft.WLED.csproj -c Release` produces both a `.nupkg` and a |
| 82 | + `.snupkg`. |
| 83 | +- Inspect the generated `.nuspec` inside the `.nupkg` and confirm `<repository …>`, |
| 84 | + `<projectUrl>`, `<readme>README.md</readme>` and a packed `README.md` are present. |
| 85 | +- Full `dotnet build`/`dotnet test` (all four TFMs) remain green. |
| 86 | + |
| 87 | +## Definition of Done (per `plans/README.md`) |
| 88 | + |
| 89 | +1. **README.md** — no consumer-facing API change; the README itself now ships in the package. |
| 90 | + No snippet change required. |
| 91 | +2. **samples/BasicConsole** — unaffected. |
| 92 | +3. **CHANGELOG.md** — record the packaging improvements under the unreleased section. |
| 93 | + |
| 94 | +## Out of scope |
| 95 | + |
| 96 | +- Changing the package icon, license file form (`PackageLicenseExpression=MIT` stays), or |
| 97 | + versioning scheme. |
| 98 | +- Publishing/CI changes — the existing pipeline already pushes `.nupkg`/`.snupkg`. |
0 commit comments