Recently I was catching up on the latest & greatest guidance for NuGet package authors (such as Meziantou’s blog and the new Microsoft docs on packaging best practices) and I realized it’s non-trivial to keep track of those on every library project you ship.
So I decided to supercharge NuGetizer with the knowledge of these guidelines, so it can be even more helpful when authoring non-trivial nuget packages!
So let’s see what’s in store for your new package!
NG0101: Default description detected
Perhaps you came across some of these popular packages and thought “How come they all came up with the same crappy description?”:
Turns out that the .NET built-in NuGet targets set this automatically for you, which isn’t actually very helpful, is it?
NuGetizer will detect this and issue a warning now:
NG0102: Default authors detected
Likewise, trying to be helpful, the .NET SDK will default the project’s Authors property
to the AssemblyName, but since the package
authors metadata
should instead be a coma-separated list of nuget.org profile names, we flag that as a
warning too:
NG0103: Package icon missing
Highly recommended to get a more professional look on nuget.org!
NG0104: Package readme missing
Package readme on nuget.org can greately improve the experience for new users! It’s a great way to highlight the key features of your project, and you should definitely consider adding one.
NOTE: if you have multiple packages and want to reuse common sections of markdown across them, NuGetizer makes this straightforward too!
As noted, NuGetizer will make sure the readme you specified as a project property is properly packed without any further configuration on your part!
NG0105 and NG0106: Package license missing or duplicate
A must-have piece of metadata.
NOTE: NuGetizer uses SponsorLink to properly attribute your sponsorship to help keep the project healthy and actively maintained. You’ll see the heartfelt thanks there too every now and then 💜.
It will also error if you have duplicate license attributes, which is not allowed:
NG0107, NG0108, NG0110: Source control information missing
Only when packing (either inside Visual Studio or via dotnet pack), additional
analyzers will check whether you’re providing the RepositoryCommit and RepositoryUrl.
These are populated automatically when using Source Link, so the diagnostics link to it automatically.
While they may seem redundant, they are not! NG0107 checks for RepositoryCommit
specifically. You might have installed Source Link but may be building a package from
a non-source controlled location.
NG0110 checks for Source Link itself, and NG0108 checks for RepositoryUrl: this
property might not be appropriate to all projects, especially if they are not open
source. The diagnostic suggests setting PublishRepositoryUrl=true for your project
if you want the Source Link-determined repo url to be published.
For example, for a non-oss project, you’ll likely still want to have RepositoryCommit
populated for troubleshooting purposes, but not RepositoryUrl.
NG0109: Project URL missing
While RepositoryUrl is inteded for source control software consumption, the
PackageProjectUrl project property should be set to a user-facing home page
where users can engage with you.
NuGetizer will default both to the same value, but suggest that you provide a unique one for the latter. It might be OK for both to be the same in case your project home page is the same as your repo home page.
NG0111: EmbedUntrackedSources not set
When EmbedUntrackedSources is set to ‘true’, Source Link will embed in your PDB the items that participated in the compile, but not are included in source control. This improves the debugging experience for your users:
As more recomendations become best practices, we’ll incorporate more diagnostics. You can also recommend new ones on the NuGetizer repository.
If you find NuGetizer useful, please consider sponsoring the project. Learn more about GitHub Sponsors.
Happy packing!
/kzu dev↻d