chore(nuget): clarify publish behavior reentrant

README.md

@@ -753,7 +753,7 @@ targets:
 ### NuGet (`nuget`)
 
 Uploads packages to [NuGet](https://www.nuget.org/) via [.NET Core](https://github.com/dotnet/core).
-By default, `craft` publishes all packages with `.nupkg` extension.
+Normally, `craft` targets raise an exception when trying to release a version that already exists. *This target diverges from the norm and allows re-entrant publishing* as it can publish multiple packages at once and the processes might get interrupted. This behavior allows us to finalize half-finished releases without having to publish a new version and play cat & mouse with the flaky upstream package repository.
 
 **Environment**
 

src/targets/nuget.ts

@@ -79,6 +79,11 @@ export class NugetTarget extends BaseTarget {
       '--api-key',
       '${NUGET_API_TOKEN}',
       '--source',
+      // Warning: `--skip-duplicate` means we will NOT error when a version
+      //          already exists. This is unlike any other target in Craft but
+      //          became needed here as NuGet repo is quite flaky and we need to
+      //          publish many packages at once without another way to resume a
+      //          broken release.
       '--skip-duplicate',
       this.nugetConfig.serverUrl,
     ];