Installation instructions for NUKE

[matkoch]

Hi everyone! I'm basically following up on another recent proposal to extend the installation instruction tabs.

Proposal

NUKE provides a nuke :add-package <package-id> [package-version] command via our global tool, which allows installing packages to the build project. The command works from any directory of a repository built with NUKE, thus covering more situations compared to the conventional dotnet add command. More importantly, though, it automatically determines how a package should be installed, which is either as PackageReference (regular libraries) or PackageDownload (tool packages). The latter is a great feature (thanks once more @nkolev92), because it allows a build to reference tools without messing with references (implicit ExcludeAssets), and works with tools in different versions (PackageReference wouldn't allow that even with ExcludeAssets).

We would like to display this command as installation instructions under a separate "NUKE" tab. Today, users naturally use PackageReference instead of PackageDownload, which often completely breaks the compilation of the build project, and overall is a sub-optimal approach.

Listing Criteria

Regarding if we meet the criteria, here are my comments:

• Signification adoption in .NET community: currently at 1.4M total downloads and around 1k downloads per day for the main package
• Actively maintained and updated: the project is continuously maintained for the last 4 years (since its creation), and as mentioned below used by a wide range of companies and projects
• Security compliance: We have repeatable builds. Publish signed packages. Have a package prefix reservation. And 2FA for NuGet.org!

Background

NUKE is a build automation system, which is created with the idea to integrate with other .NET tools natively. That means it uses regular C# projects for the build implementation and thus comes with IDE integration out-of-the-box, including navigation, refactoring, and debugging. It is well adopted with almost 1k downloads per day, and many companies and projects are actively using or transitioning to it (e.g. OctopusDeploy, JetBrains, AvaloniaUI, ASP.NET Boilerplate, CsvHelper, FluentAssertions, HotChocolate).

---

We and our users would really appreciate if this proposal would be accepted! 🙏

[totollygeek]

Visual proposal

Here is an example of how that could look like

[JonDouglas]

Hey everyone,

First off, thanks so much for writing a proposal to add the NUKE DSL instructions to NuGet.org! From an initial review, we believe that NUKE meets majority of the requirements set via #4510 (comment). There is one requirement that we aren't too sure of given the unfamiliarity of NUKE, and that's the presence of a User Agent in the client tooling to understand package download usage from NUKE compared to other client tooling. We are hopeful that it's possible to add a custom NUKE user agent to the NuGet APIs you're using such as:

• UserAgent.CreateUserAgentString()
• UserAgent.SetUserAgentString()

Examples: https://github.com/NuGet/NuGet.Client/search?q=useragent

(We can help further if there's good places to hook into)

This would help us understand what client is downloading a package & would help in the long-term with the ecosystem being more data-driven! You can see this example of what I mean by that:

https://www.nuget.org/stats/packages/Microsoft.EntityFrameworkCore?groupby=Version&groupby=ClientName

Additionally we look at the usage of the tooling in various .NET projects. I think that is mostly covered by your proposal with an expanded list here: https://github.com/nuke-build/nuke#users.

We'd ask that before we can approve a contribution from the NUKE project to add these instructions, that a custom user agent is added to the tooling. Once that is completed(if it's feasible), we can move forward with a contribution to add the instructions & merge when initial data comes in.

In the meantime, we are also encouraging the use of our new proposal process. This helps us go through the rounds of the various considerations made & gives people in the community an opportunity to bring up questions & feedback prior to it being accepted. If there's time to create a quick proposal & send a PR to nuget/home, that would be wonderful.

In short:

• Significant adoption in .NET community ✔⚠(Addition of user agent for long-term ecosystem data)
• Actively maintained and updated ✔
• Security compliance ✔

Action Items for NUKE project maintainers 📋:

• Investigate the inclusion of custom user agent into NUKE tooling to report the NUKE client in package statistics.
• Creation of a NuGet proposal to provide the community a place to discuss & be accepted if no major objections/considerations.
• Consideration for NUKE tab instruction contribution for NuGet packages & .NET tools (If applicable) - See: Implementation of Cake tab with instructions for NuGet packages #8434 & Implementation of Cake tab with instructions for .NET Tool packages #8440 for recent examples.

If this all sounds reasonable, then we'll review the proposal in the next couple weeks while awaiting the investigation of the user agent inclusion. Please let me know if there are any questions, comments, or feedback to these initial considerations. We're trying to make these considerations as transparent as possible & still have a ways to formally document them.

Note: We're trying our best to not change any requirements, but rather to improve our processes. As you may imagine, the requirements list in 2017 still reflects the considerations, but we want to ensure the long-term success by being data-driven and learning from recent contributions as well.

[matkoch]

@JonDouglas generally speaking NUKE doesn't act as a dedicated NuGet client. It fully operates on either dotnet CLI or the Microsoft.Build package, which makes it transparent, up-to-date, and most of all integrated with all the developer tools that exist. If you need a user agent, it probably could be added in some way, but I'm gonna say it would be rather artificial:

• At design-time, a build author can add a package with the mentioned command nuke :add-package <package-id>. This simply adds the PackageReference item to the csproj file using Microsoft.Build infrastructure, and then performs a dotnet restore on the build project which triggers the download to the global NuGet cache. It is only converted to PackageDownload if the package contains a ./tools directory. Providing a user-agent would require replacing the dotnet CLI call, which implies more maintenance, but – yes – doable.
• At build-time, the build project is restored and built with dotnet build. I'm afraid requiring a user-agent at this moment could imply breaking the minimal bootstrapping mechanism of NUKE, which is particularly something that users have benefited from because it is resilient to any upstream changes and hence less fragile. It could be possible by making a second roundtrip to NuGet.org, but I guess it's not in the interest of anyone to download packages twice.

Is it possible by any chance to set a different user-agent from outside? For instance with an MSBuild property /p:NuGetUserAgent=.. or as an environment variable NUGET_USER_AGENT ? From a quick glance there is no such thing, but maybe it could be added? A similar approach already exists with NUGET_PACKAGES for instance.

I hope it's clear that this proposal is laid out for more efficient and correct package consumption, and I'd appreciate it if we can find a solution to this without degrading the existing native integration with .NET tools.

[JonDouglas]

Thanks for the quick response!

We figured that might be the situation, but wanted to bring it up for feasibility & consideration. To my knowledge, no such property or ENV variable exists but could be something we break-off separate to this proposal to be considered for the future to not disrupt the native integration while also reporting the client use.

Let's move forward with the other action items to keep the momentum.

Thanks!

[matkoch]

Just to clarify, the only other action you need me to approach is to create the proposal according to the new process ? I guess the PR is something that can wait until there is a decision.

[JonDouglas]

@matkoch Yes that's correct. The contribution PR can wait until the proposal PR is reviewed & accepted by the community & NuGet.

[matkoch]

I think we can close this. Follow-up is linked above.

[zivkan]

reopening as per this comment: NuGet/Home#10784 (comment)

[matkoch]

@zivkan sorry i did not know :) should i update my original post maybe to only link the new spec?

[joelverhagen]

@matkoch, this change is now live on PROD. Thanks again for your hard work here!

[matkoch]

@joelverhagen wasn't hard actually :) Thanks for your assistance!