New experience for NuGet Documentation

Last month, we launched a preview of the revamped Nuget docs experience. We made a number of improvements:

  1. New quick-starts for creating and consuming packages.
  2. End to end guides for new platforms such as .NET Standard and UWP.
  3. A simpler and more intuitive organization of topics.
  4. Left pane of contents serves as an index and allows you to glance at all topics.
  5. Cross-references with links to recommended reading, related topics and reference docs.
  6. A modern look and feel to the docs site.

We would like to thank you for trying out the preview and giving us valuable feedback. We have incorporated your feedback and ironed out some wrinkles we found along the way. Today, we are going live with the new experience on docs.nuget.org.

Will my existing references to documentation break?

Existing references should still work. We have updated the old docs with permanent redirects which will redirect you to the new page. If you find a broken reference, please open an issue on our GitHub repo and we’ll work to get it fixed.

How can I contribute?

Every page that allows contribution has an obvious “Edit in Github” link at the top. This link will you take you to the md file. Feel free to make changes and create a PR from your branch. The NuGet team will review the change and work with you to get it merged.

If you would like to raise a request for new docs or changes to existing docs, feel free to open a new issue.

What’s next?

Over the next few weeks, we will continue to make more improvements to the docs with respect to content and organization. In addition, we are considering starting our docs migration into docs.microsoft.com in the coming months. Since NuGet is an integral part of the .NET Ecosystem, this move will make it easier to find and navigate our documentation. Moreover, we’ll have a consistent way to get feedback and enable contributions to docs from our users.

We want to hear your feedback!

We want NuGet to meet the evolving needs of our community. If you would like to share your pain points and your current and future needs, use the calendly link to set up a quick 15-30 min call with us. If you would like to send us an email instead, hit us up at feedback@nuget.org.

You can also leave a comment below, and as always, if you run into any issues or have an idea, open an issue on GitHub.

Published September 20, 2016 by Karan Nandwani

Changes to Expiring API Keys

In June, we published a blog post announcing Expiring API Keys. We received a lot of great feedback from the community about it. In retrospect, we did not do a great job explaining the motivation and reasoning for this security measure to the community.

This post goes into more detail about why we introduced Expiring API Keys, the immediate changes we are making to the design to address feedback, and improvements to our process to prevent a similar situation from happening in the future.

Your Feedback

Let’s start with a summary of the most consistent feedback we heard from the initial plan:

  • Without automated renewal mechanisms, this feature would break CI builds and automation.
  • Large organizations, such as Serilog which has over 60 repos, would find it difficult to co-ordinate and ingest Expiring API Keys because their projects use a variety of CI and build systems.
  • Some packages are updated infrequently (only 3-4 times a year.) A 90-day expiration would cause them to have to renew the key each and every time they update.
  • Parallels with other systems were drawn (GitHub, Lets Encrypt, NPM, etc.) to point out that they were not imposing such measures in the name of security and if they did, they had auto-renewal mechanisms in place to address CI scenarios.
  • This introduces additional friction which is unnecessary for my scenario.

Thanks for this great feedback. It caused us to press “pause” on our efforts and re-think the problem of leaked API keys and the plan for it.

Why Expiring API Keys?

Over the past few years, you have probably read stories about accounts being hacked on various online sites. Almost everyone has received a notification that you need to change your password on a site. Online security is a real challenge. API keys and username/passwords are not the same, but they do have a lot of similarities and have a shared set of risks on leaks and theft.

This change was envisioned to solve 2 problems that we have today in NuGet.org.

Leaked Keys

Leaked keys are a security hole like any another leaked credential. If a developer of a popular package has their API key stored on their box, CI machines or personal accounts and their systems or accounts gets compromised, it would be trivial for the attacker to take advantage of this leak and publish malicious content by updating a popular package. While some key leaks are exploited immediately, some attackers hold on to keys until the circumstances are in their favor to exploit it for the maximum gain.

Stale Keys

The NuGet ecosystem is about 5 years old now. There are many NuGet.org API keys that have not been used for greater than a year and a smaller set that have never been used to push packages. Many of the accounts tied to these keys could be dormant and might be unmonitored by the original account owners.

If any of these dormant accounts or API keys are compromised, attackers can push updates to existing packages or create new packages that contain malicious content from these accounts.

Rotating credentials after a set time period is a proven way to minimize this threat if not completely neutralize it. An example of this would be rotating passwords for users and service accounts in enterprises.

Immediate changes to the feature based on your feedback

  • Starting today, existing API keys that are used at least once each year will never expire. This approach enables the most active package maintainers to effectively opt-out of API key expiration. You can set expiry between 1 day and a year when you create or renew an API key.
  • We will expire all API keys that have been unused for a year immediately. This change will prevent dormant and unmonitored accounts from publishing malicious packages.

What’s coming next?

While the plan above addresses some of the feedback that we got from the community and some of our goals in the short term, it does not address all the feedback.

We are working on incorporating more pieces of feedback that like auto renewal mechanisms and multiple API keys. We will publish a blog post in the next month or so detailing our proposed design.

How are we changing rollout of security features?

In hindsight, given the scope of the feature and the impact to the ecosystem, we should have started by having the discussion with the community before rolling this out.

Some security related features and changes cannot be disclosed in advance to protect operational security and minimize the chances of an attack. But there are others like Expiring API keys, that can be shared to get feedback before rolling it out to NuGet.org. We promise to do better in this regard in the future.

We want to hear your feedback!

If you have more specific feedback on this topic, we have a GitHub issue open here where we can continue the discussion.

We want NuGet to meet the evolving needs of our community. If you would like to send us an email, hit us up at feedback@nuget.org. You can also leave a comment below, and as always, if you run into any issues or have an idea, open an issue on GitHub.

Published August 25, 2016 by Harikrishna Menon

The path towards better documentation

Update 9/20 (11:00 A.M PST): The revamped NuGet Docs experience is now live on docs.nuget.org. Read more about it here - New experience for NuGet Documentation

docs.nuget.org is the authoritative guide on everything NuGet. It is used as reference by nearly 180k developers with over 500k page views a month. Summary of the most consistent feedback we heard is given below:

  1. The grouping is not intuitive and makes it difficult to find the right document.
  2. Figuring out the end to end steps to build packages for new platforms is hard.
  3. Lack of indexing and cross referencing makes it difficult navigate between samples, reference docs and release notes.
  4. Some items only appear in release notes and blogs, but do not appear in the final docs.

In this post, we are going to talk about the changes we recently made based on your feedback, and plans going forward.

Before diving into details, we would like to thank a number of people who have helped us review and give feedback on these changes or inspired us to write new guides. Some of them have written a number of blog posts and tools that has significantly helped the community in understanding various package authoring techniques, NuGet concepts and APIs. There are many more who provided feedback through issues, tweets and other channels.

What did we change?

We have revamped the NuGet docs experience and we have a preview for you to try out. NuGet Docs Preview addresses the majority of feedback from the community. Just to be clear, we are not replacing docs.nuget.org just yet.

We have made several improvements including:

  1. New quick-starts for creating and consuming packages.
  2. End to end guides for new platforms such as .NET Standard and UWP.
  3. A simpler and more intuitive organization of topics.
  4. Left pane of contents serves as an index and allows you to glance at all topics.
  5. Cross-references with links to recommended reading, related topics and reference docs.
  6. And finally, a modern look and feel to the docs site.

new nuget docs landing page

How are the new docs organized?

  1. Quickstarts - These are very basic guides for both authors and consumers to get started
  2. Guides - The idea here is to give you everything you need to know to execute a scenario end to end. Some of the key guides we have built are:
  3. Creating, Consuming and Hosting packages
  4. Tools, Schema, API and Visual Studio Extensibility - Reference documentation
  5. Policies - FAQs, Governance, and the policy around Dispute resolution and Deleting packages
  6. Contribute guidance has been moved to the Nuget/Home wiki on Github

Will my existing references break?

No, existing references will not break. When we update docs.nuget.org, we’ll have permanent redirects in place that will redirect you to the new page.

How can I Contribute?

We made the contribution link a lot more obvious. Every page that allows contribution has a “Edit in Github” link right at the top. This link will you take you to the md file. Feel free to make changes and create a PR from your branch. The NuGet team will review the change and work with you to get it in.

edit in github

If you would like to raise a request for new docs or changes to existing docs, feel free to open a new issue.

What are we going to do moving forward?

With the advent of .NET Core, the NuGet community is growing by leaps and bounds. We understand that we have to lower the barrier to entry to make it easy for authors to create packages and for users to consume them. The first step there is to have fantastic documentation in place that enables this.

Over the next two weeks, we’ll closely look at any feedback on NuGet Docs Preview and iron out any wrinkles before updating the old site (docs.nuget.org).

In the coming quarter, we are looking into starting our docs migration into docs.microsoft.com similar to .NET Core documentation. Since NuGet and .NET are tied at the hip for the majority of its use cases, it’ll make it easier for our users to find and reference docs. In addition, we’ll have a consistent way to get feedback and enable contributions to docs from our users.

We want to hear your feedback!

We want NuGet to meet the evolving needs of our community. If you would like share your pain points and your current and future needs, use the calendly link to set up a quick 15-30 min call with us. If you would like to send us an email instead, hit us up at feedback@nuget.org.

You can also leave a comment below, and as always, if you run into any issues or have an idea, open an issue on GitHub.

Published August 22, 2016 by Karan Nandwani

Older Posts