SolvedNuGetGallery Add Cake instructions for NuGet packages

Background

Cake (C# Make) is a free and open source cross-platform build automation system with a C# DSL for tasks such as compiling code, copying files and folders, running unit tests, compressing files and building NuGet packages.

image

Cake is widely used by thousands of open-source projects, is the third most downloaded .NET tool at the moment with over 4 million downloads, has a healthy community of contributors, and is a member of the .NET Foundation.

One of the features of Cake is the ability to consume NuGet packages from any NuGet compatible feed, and leverage them in the build orchestration process. For example, within a Cake build, a user can reference the Polly NuGet package, and leverage all of its features, defining and executing different Polly policies.

NuGet packages can be used in Cake in a variety of ways:

  • As a regular NuGet package (Package Reference, packages.config, NuGet Package Manager UI, etc.) on a Console application.

  • As a Cake Addin (#addin). In short, this means: Download the NuGet package, and load the assemblies within it into the host process executing the build process. Virtually any NuGet package containing .NET assembly(ies) can be loaded as a Cake Addin. e.g. #addin nuget:?package=Polly&version=7.2.1

  • As a Cake Tool (#tool). In short, this means: Download the NuGet package, and extract its contents to a folder, so that its files become available to the build process. Virtually any NuGet package can be loaded as a Cake Tool. e.g. #tool nuget:?package=7-Zip.CommandLine&version=18.1.0

  • As a Cake Module (#module). In short, this is very similar to Cake Addin, with the exception that modules are loaded earlier in the lifecycle and can replace and/or add Cake features that can be leveraged by the build process later. e.g. #module nuget:?package=Cake.Npm.Module&version=0.1.0

  • As a Cake Recipe (#load). In short, this means: Download a NuGet package containing Cake scripts, and merge these scripts into the current build, allowing for sharing of reusable snippets of code. e.g. #load nuget:?package=Cake.Recipe&version=2.1.0

Proposal

We'd like to display installation instructions on how to use NuGet packages with Cake, in the NuGet Gallery, on a new tab with the title "Cake Build", which would display a tailored set of instructions if a package is detected as being built specifically for use with Cake (Cake Extension) or generic instructions otherwise.

The criteria we'd like to use for detecting if a package as built specifically for use with Cake would be the presence of specific tags in the package metadata:

Cake Addin

  • If a package contains the tag cake-addin, we assume its author meant for this package to be consumed as a Cake Addin. As such we would show a tailored instruction to install as a Cake Addin:

image

Cake Module

  • If a package contains the tag cake-module, we assume its author meant for this package to be consumed as a Cake Module . As such we would show a tailored instruction to install as a Cake Module:

image

Cake Recipe

  • If a package contains the tag cake-recipe, we assume its author meant for this package to be consumed as a Cake Recipe. As such we would show a tailored instruction to install as a Cake Recipe:

image

Other packages

  • If a package does not contain any of the known cake- tags, we'd display generic instructions for the user to consume the package either as a Cake Addin or as a Cake Tool, and leave it to the user to choose what is more appropriate for their scenario.

image

3rd-Party NuGet client listing criteria

We believe Cake meets all the criteria for being listed as a 3rd-party client on nuget.org:

Implementation

Members of the Cake team would send one or more pull-requests to implement the final design that ends up being agreed, based on the above.


/cc @joelverhagen @anangaur, @jcjiang

21 Answers

✔️Accepted Answer

@augustoproiete, Cake friends, et al - this is now live on PROD! For example a cake-recipe:
https://www.nuget.org/packages/Cake.Recipe/

image

Thank again for all of the feedback! We'll keep an eye on customer feedback and usage in the coming months to understand if any further steps are required.

Other Answers:

While IMO the first three points (which are based on the cake-* tags) are a good idea, I want to bring into question if we really want to add the "Cake Build" tab to all packages.

Reasoning:

  1. The probability is near to zero to include packages like Castle.Core, Microsoft.EntityFrameworkCore, Microsoft.AspNet.Mvc, ... inside a build script. So why add an distraction there (the smaller an UI the better).
  2. Cake Build is one build system among lots of others and there are many other systems which allow to reference NuGet packages => do we want to have 5, 10, 20 such tabs in the future? If "yes", we should move it to an "other" sub menu right now (and maybe also the "Paket" one) to avoid UI cluttering.
  3. If for some Cake power users it is really important to have this copy to clipboard shortcut for any package, the Cake authors can offer a browser extension to add this feature.

Hey @ulrichb, thanks for the feedback!

My perspective is that it is very hard to guess which purpose a user/package consumer comes to the package details page for. The vast majority of page views on NuGet.org are unauthenticated (98%+ IIRC) so we have little/no hint that if the user is a Cake power user or not. Also, my understanding is that some general purpose dependency packages (such as Polly in the example above) are quite usable in Cake recipes. Instead of trying to guess we think it is okay to ship the proposal as is.

As mitigating factors, consider:

  • the selected tab is "sticky" per browser local storage. So if a user doesn't want Cake, their other tab selection will remain so the toggling/confusion will be minimal.
  • we can start with this proposal and react to user feedback and observe usage. We emit a Application Insights event any time the copy button is clicked so we can get a better feel for what is the very best decision in the long run.
  • as we further enable multiple package types in the future (NuGet/Home#10468) we can revisit this topic and choose the best next steps, given we would have experience and data at that point
  • at the bottom of the tab will be a link so users can reach out to the Cake team. This will help folks gain an understanding of what Cake is and how to use it. Perhaps this is even a little "on-ramp" so users can have another technology to choose from.

Regarding your specific points:

The probability is near to zero to include packages like Castle.Core, Microsoft.EntityFrameworkCore, Microsoft.AspNet.Mvc, ... inside a build script. So why add an distraction there (the smaller an UI the better).

I agree for those specific cases. Unfortunately given "weakly typed" nature of NuGet packages (by that I mean few concrete attributes we can observe to make UI decisions like this) it's hard to make the call on the fly of whether a package you're viewing is appropriate for Cake. As one of the original designers of NuGet package types I hope that we can eventually move to a place where package capabilities can be advertised more conclusively in the future. Right now there are blockers in the VS UI but perhaps in the future after this is resolved package authors could advertise "yes my package makes sense in Cake" with a package type and simply release a new version of their package to adopt this more "strongly typed" approach.

Cake Build is one build system among lots of others and there are many other systems which allow to reference NuGet packages => do we want to have 5, 10, 20 such tabs in the future? If "yes", we should move it to an "other" sub menu right now (and maybe also the "Paket" one) to avoid UI cluttering.

We have talked about this several times in team meetings and such and I agree it's a concern in the long run. We certainly don't want to clutter the package details page too much so we need to strike a balance between what is useful to "enough" users and what is "too much".

Back when we worked on the Paket tab (which, if you want to dig up history, had it's own controversy and which I was personally involved with 😨) we defined some criteria which would allow us to be more objective regarding these decisions in the future. You can read the criteria here: #4510 (comment). The NuGet.org team felt that the Cake team has sufficiently met this criteria.

For the "Cake" tab, our most common desktop screen resolutions will still show the tabs on a single row. For phone users, the tabs are often already spread across two lines so adding one more tab will not make the situation worse.

As the number of tabs grows, we have an internal UX board that can help brainstorm better solutions for how to display this information. I don't know the answer long run but I'm confident it's not an unsolvable problem 😄.

If for some Cake power users it is really important to have this copy to clipboard shortcut for any package, the Cake authors can offer a browser extension to add this feature.

Very true, in fact this option exists for any tool that leverage NuGet packages and has some "installation" flow. From our package download telemetry, we see high adoption of the Cake tool so we felt that it was a good time to add it to the list of built-in tabs.

I know this is rather long winded, but I wanted to clarify some of the factors we are considering.

@augustoproiete, @gep13 - do you have any additional points you want to add?

I appreciate your feedback and my team will be keeping our eyes open regarding user feedback in this area. Please let me know if you have any follow-up questions.

@joelverhagen I appreciate your openness regarding new additions to the tabs, and I'm also fully in favor of such proposals.

Being listed on NuGet is very much an honor for any creator. I know you put an info text there, but the perception is still that the tool is highly recognized / recommended by the NuGet Team.
Cake is only one of at least 5 solutions in the field of build automation. If you say "ramp-on technologies", I wonder if you'd also be open to list other alternatives there as well.
One thing you have to keep in mind is that some of alternatives don't actually require a special syntax to reference packages, they were designed around the good (not so) old PackageReference way. Basically, they wouldn't require an info-text per-se. However, not listing them would, imho, give a wrong impression and implicit recommendation/advantage for the others.

TLDR: What would you think about a unified "Build Systems" tab?

I like Cake. Cake is straight to the point. And who can complain that there's free cake? It's really up to @augustoproiete with regards to what best represents Cake here if there's no major concerns other than names(Hardest problem in programming). Those details can be figured out in a PR.

Given that this proposal has been accepted, we will write up a quick proposal based on the initial issue description & answered questions thus far and open up a PR for any final feedback to give the contributor(s) to resolve while they work to provide implementation PRs of the proposal (which will likely be shared here as well).

https://github.com/NuGet/Home/tree/dev/meta#what-happens-when-a-proposal-is-accepted

I will send a message here with a link to the proposal in our main repository when such a PR exists & is ready for comments. I'll do my best to capture all the details thus far, but may need help from the Cake team to ensure I captured everything 😊

Related Issues:

14
NuGetGallery Add Cake instructions for NuGet packages
@augustoproiete Cake friends Background Cake (C# Make) is a free and open source cross-platform buil...
11
NuGetGallery Improve search relevance on NuGet.org
@skofman1 I think they should be based on popularity much more For example when I search for csharp ...