Add Cake instructions for NuGet packages

[augustoproiete]

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.

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:

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:

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:

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.

3rd-Party NuGet client listing criteria

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

• ✅ Significant adoption in .NET community: Cake is widely used by thousands of open-source projects, is the third most downloaded .NET tool at the moment with over 4 (four) million downloads
• ✅ Cake is actively maintained and updated: Cake published over 110 releases since 2014 (with 10 releases in 2020), has a healthy community of contributors, and is a member of the .NET Foundation
• ✅ Security compliance: Cake is compliant with the latest security requirements as implemented by 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

[joelverhagen]

Hey @augustoproiete, excellent work on this proposal! The team today met regarding this proposal and we have decided to accept it! 🎉

You may proceed with submitting a PR to NuGet/NuGetGallery based on package tags, i.e. just what you proposed above.

@JonDouglas will be pushing the conversation on NuGet/Home (NuGet/Home#10468) regarding package types. If and when the package type change lands, we can wait for sufficient adoption and perhaps switch away from the tags approach to the package type approach. But we don't want to block the surfacing of a Cake tab on this longer term change in VS behavior.

One question from the team: does Cake verify package signatures?

As of .NET 5/NuGet 5.8, NuGet has cross-platform support for package signature verification. This can bolster the security of package consumption, protecting against tampering and even enforcing strict client trust polices.

[gep13]

@joelverhagen this is great news!

Can you confirm if you are happy with the tags that have been suggested in this proposal? If so, we can start the process of adding them to packages while this proposal of being worked.

[ulrichb]

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.

[augustoproiete]

@joelverhagen This is great news! Really appreciate your help and the team in moving this forward. I'll get started on the implementation, and send a PR as soon as possible.

Regarding package signature verification, it's not a feature we've implemented yet but we're definitely interested in adding it to Cake in a future version. We're tracking it here - cake-build/cake#3178

[joelverhagen]

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 (Feature request: Installation of nuget packages with custom types 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.

[ulrichb]

@joelverhagen

Oh, didn't know about the requirements list in #4510 (comment).

Just one small suggestion: Because moving entries later is kind of an "UX breaking change", I personally still would implement the "sub menu" UI (or whatever) right now. (And as the requirements above are not that high, I think this will happen in the foreseeable future.) If - i.e. based on your Application Insights data - you see that some specific option is in active use, it can still be "promoted" to a top level tab (which is "less UX breaking").

In any case, thanks for your detailed answer!

[joelverhagen]

Just one small suggestion: Because moving entries later is kind of an "UX breaking change", I personally still would implement the "sub menu" UI (or whatever) right now. (And as the requirements above are not that high, I think this will happen in the foreseeable future.) If - i.e. based on your Application Insights data - you see that some specific option is in active use, it can still be "promoted" to a top level tab (which is "less UX breaking").

Yeah, great idea.

Let's keep consider this idea and others as a) the number of tabs grows or b) the data says any of the tabs are essentially unused. We need to think about accessibility and small form factors but a sub menu seems do-able. I think at that same time we would review the UX holistically anyway.

Like one additional idea we've thought about is a little icon per tab next to the name. This would maybe help distinguish tabs but would leave us with less room. We also thought about a different background color for the most popular tabs which would make them "pop" more. It also might be good to have a "getting started" link on each tab so that people unfamiliar with the tool can learn easily.

That being said, I am pretty bad at web UX 😅 so, yeah, we would meet with the experts at Microsoft when we have a good evidence that the current thing isn't working.

[gep13]

@joelverhagen said...
do you have any additional points you want to add?

Not from me no, I think you covered everything very well.

I did have one outstanding question though from comment above.

[Inspyro]

@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?

[joelverhagen]

I did have one outstanding question though from comment above.

@gep13, sorry missed that. You may proceed with the cake-addin, cake-module, and cake-recipe tags as specified above. Just keep in mind that it's not live yet and we don't have a firm timeline (need PR, review, merge, deploy). So users may be frustrated that their tabs aren't working as expected if they jump in quickly.

[pascalberger]

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.

The goal of this issue should not be to promote specific build engines. It's about giving user of a popular client of the NuGet gallery, Cake scripting engine in this case, instructions how to use packages with this specific client. If a library or tool, like Cake Frosting, to stay with the Cake ecosystem, just use package references this documentation for the user is already available in the first three tabs. Adding a tab for the Cake scripting engine is not about promoting Cake scripting engine over other, like Cake Frosting, but to provide instructions for all users of different clients.
Mentioning something like Cake.Frosting in these tabs, would be very weird, as it would be promoting a library or tool, hosted on nuget.org, on every package page.

[Inspyro]

The keyword here is "perception". And if it's about the scripting experience, then why call the tab "Cake BUILD" and not "Cake Scripting" ?

[pascalberger]

The keyword here is "perception". And if it's about the scripting experience, then why call the tab "Cake BUILD" and not "Cake Scripting" ?

Cake Scripting, or Cake Script Runner, the term used in docs, would work perfectly fine, even though it is a little bit longer. But I think this is a detail which can be discussed in a PR review.

[matkoch]

Providing more accessible wrappers/aliases around other popular packages is one of the claimed goals for addins (Cake.Email for MailKit, Cake.Json for Newtonsoft.Json, Cake.Yaml for YamlDotNet). Doesn't the "other packages" proposal diminish that goal? Yes, there are packages that don't have a wrapper, which could be used inside Cake. But how much of a thing is that actually? I was under the impression that Cake is popular as a build automation tool (see OP), and not as a general-purpose scripting engine.

It boils down to the question initially asked by @ulrichb. Paraphrased: how likely is it to actually consume "other packages" in Cake. @joelverhagen you were talking about "weakly typed" packages, and generally I agree. Given my argument from above though, I think the tags are sufficient, more meaningful, and generally on point for the majority of use-cases.

[daveaglick]

I wonder if you'd also be open to list other alternatives there as well.

I think this question may getting lost, but it's an important one given that there's a clear answer. The NuGet Team has published criteria that answers this exact question and the answer is "yes". As @joelverhagen pointed out, the goal of such criteria is to ensure that such decisions are as unbiased and objective as possible. As far as build tools go, Paket has met this criteria. Now it's been determined by the NuGet team that Cake has also met this criteria. I'm positive the team would be happy to accept any other tools that also meet the criteria as well, dealing with any UX issues when and if they arise.

As to the issue of whether syntax for specific tools should be listed at all (which seems like the subject of most of the following here), I suspect the publishing of acceptance criteria probably puts that issue to rest - the NuGet team has determined they should, following debate on that topic, that doing so provides value to their users, and that the selection of such tools should be objective and not limited in either number or type. That discussion was had and resolved in #4510. The way I see it, there are two things left to debate in this issue if such debate is needed:

• Whether Cake as a tool did, in fact, meet the laid out criteria. Personally I think the case for this was made pretty well but it could always be challenged.
• Whether the criteria itself is flawed or needs revising. I haven't actually seen much discussion of that in this issue, though I'd guess the NuGet team would be willing to discuss that in a separate issue.

I'm obviously biased to move forward (which itself demonstrates why having objective criteria is important), but I'm not sure what more anyone is gaining by reopening the discussion that was already resolved in #4510.

[joelverhagen]

Hey folks, thanks for all of the feedback in this regard. I'll try to address the questions above, point by point, and then summarize at the end. Skip down there for a tldr if this is too many words 😄.

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

@Inspyro, I'm not sure if I fully understand this proposal. Do you mean to call the proposed "Cake Build" tab as a more generic "Build Systems" tab? Or do you mean a new tab entirely in addition or in lieu of "Cake Build"? For the Cake case, indeed there is a special syntax so if that syntax is going to be on NuGet.org at all, it will need to somehow be clearly labelled as a "Cake" think.

Regarding that specific title, I think there is definite potential for a generic-ish tab is we can figure out two things:

1. What are we expecting this generic category to encompass? Perhaps I am speaking from ignorance here so could you perhaps enumerate several of the other well-known tools that don't have special syntax that would fit in this tab?
2. The title of the tab should not be confusing compared to the existing ones. I fear that for beginners a term as generic as "Build Systems" might actually result in more confusion. For example, depending on someone's experience and perspective, you might even say NuGet client or NuGet client integration with MSBuild is itself a "Build System" so should it those NuGet client commands go under there too? I think specific = better in this way.

As a member of the NuGet team I can tell you that terms in the dev tools space are often conflated/mixed/overloaded especially when speaking to people with different backgrounds. One thing I think that Cake tab plus the existing tabs do well is that they are precise. Well, except for the default "Package Manager" which is really a VS thing... "VS Package Manager" is maybe better 😅. But my point is today they are specific so users can perhaps avoid tabs they don't recognize since they know the titles don't apply to them. If we do a generic "Build Systems" it may be confusing. It would also need a UX change probably with multiple copy buttons (one per tool).

The keyword here is "perception". And if it's about the scripting experience, then why call the tab "Cake BUILD" and not "Cake Scripting" ?

@Inspyro, the Cake folks on this thread can correct me here, but my understand is the "Cake Build" term is the disambiguating full name of the product. For example, I see their website is "cakebuild.net" and the GitHub organization is "cake-build". I fear "scripting" might be a term that's even more overloaded than "build". For example, some people call Python programs "scripts" or Python a "scripting language" (perhaps alluding to its interpreted nature) but for Cake -- the tool is intended to specifically be used in the "build" step of a developers inner loop so I think the more specific term is appropriate.

Cake Scripting, or Cake Script Runner, the term used in docs, would work perfectly fine, even though it is a little bit longer. But I think this is a detail which can be discussed in a PR review.

@pascalberger, personally I feel that shorter is better, pushing the horizontal space issue down the road a little further. Also, my reason above is that "Build" is perhaps a less ambiguous term. If the Cake team prefers to change it to "Cake Scripting" and that is truer to the product branding/Cake community's perception then I think we're open to the change. I'd like to run it by the team though. We can decide that on the PR as you said.

Doesn't the "other packages" proposal diminish that goal? Yes, there are packages that don't have a wrapper, which could be used inside Cake. But how much of a thing is that actually? I was under the impression that Cake is popular as a build automation tool (see OP), and not as a general-purpose scripting engine.

@matkoch, I think you've touched on the most controversial part of the proposal. Does it make sense to put the tab on a page with no Cake types (or package types in the future). I think we'll get a lot of different opinions on this matter. Our data is not very telling in this area. From our data, we know that Cake and Paket are the top two 3rd party user agents showing up in package downloads.

Given the good examples @augustoproiete has provided using Polly in Cake scripts and given the minimal concrete data we have to prove or disprove either perspective, my feeling is that we should ship this experiment for the Cake Build tab and wait for customer feedback (positive or negative) and then observed telemetry on the "Copy" button, that is how frequently are people actually clicking the copy button on the Cake tab. This will allow us to make an informed decision in the future.

I'm obviously biased to move forward (which itself demonstrates why having objective criteria is important), but I'm not sure what more anyone is gaining by reopening the discussion that was already resolved in #4510.

Thanks for the summary @daveaglick. I think it's spot on. @augustoproiete has met the criteria.

I'm happy to answer more questions here but I think @JonDouglas / @jcjiang will be moving this specification to a more formal place in the future and putting it in our standard format (which is new and we're trying to standardize on). That will be another place to provide more feedback. Apologies if I missed anyone. Let me know.

tldr: we will be accepting the proposal as-is, including the Cake tab on untagged packages. On forthcoming PR from @augustoproiete, we can decide on specific wording (Cake Build vs. Cake Scripting). After this ships, we will be listening for clear user feedback indicating whether current approach works or needs some tweaking (UI-wise or otherwise). We can support any future/counter proposals with data in addition to opinion since we keep counters on how often people click the copy button on each tab.

[matkoch]

@joelverhagen thanks for clarification. Maybe we can go with just "Cake"? That would be shorter and allow potential other build candidates to blend in more nicely. "Aaa" and "Bbb" instead of "Aaa Build" and "Bbb Build". (I will probably follow up with another proposal.)

Maybe we can also add some more information about the tools? I still think Cake (and others that may follow) are quite different as "NuGet client" compared to NuGet and Paket CLI for instance. Otherwise it may cause confusion to newcomers, like "can i put this in my csharp file?".

[JonDouglas]

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 😊

[joelverhagen]

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

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.

[augustoproiete]

Thanks a lot for all the help with getting this one though @joelverhagen and NuGet team!!! 📦 🚀