I've made changes to the tech spec based on feedback I've received, specifically addressing concerns about the automatic packing of READMEs (now disabled) and the Validation strategy (who validates the actual markdown file). I wasn't able to request reviews from some of you through the Reviewers tab, so I'm tagging you here to request comments/feedback/approvals.

@zkat @zivkan @sbanni @erdembayar @rrelyea @srdjanjovcic @cristinamanum @heng-liu @donnie-msft

Open Questions
Are there any other validation checks to do when packing a Readme?

When a user packs a NuGet package without a README, there should be a warning.

Considerations

1. Should we warn users if the Readme property is empty?
   Based on feedback from both the NuGet team and customers, we should not do this. The goal of encouraging user adoption of Embedded Readmes can be pursued as part of a separate Package Quality endeavor.

I believe we should set a standard with this feature today. READMEs are a critical component for someone to not have to navigate away from NuGet.org or Visual Studio in the sense that they can learn about the package & get started with it quickly. Many customers said they would prefer to not have to go to GitHub to view the README if possible.

2. Automatically packing a Readme file from the base directory
   Similar to the above point, this functionality is not something that we will look to add right now. Relying on explicit user input for the metadata is more desirable, and avoids springing any surprises on customers.

Does this mean adding a README by default? I don't think we need to do that for the scope of this spec.

3. Enforcing a size limit on Readme files on pack
   Originally, we intended to enforce a 1 MB size limit on Embedded Readme files both while running pack on the Client-side and while using push to upload to NuGet.org. However, since we do not want to impose such size restrictions on users looking to upload packages to private or local feeds, we decided against throwing an error for this on pack. Now, the user can run pack to create packages with Readme files over 1 MB, but will receive an error if they try to upload such a package to NuGet.org, which enforces a strict 1 MB limit.

The follow-up question here is that most readmes should generally be in the KB range & all resources for the README is hosted somewhere else like github content or another location. Will embedded readmes support this similar concept where outside resources can be accessed or will users need to embed those resources as well?

I followed up with Jon in chat regarding the above, but here is the response I gave for transparency:

1. I believe we should set a standard with this feature today. READMEs are a critical component for someone to not have to navigate away from NuGet.org or Visual Studio in the sense that they can learn about the package & get started with it quickly. Many customers said they would prefer to not have to go to GitHub to view the README if possible.

As @zivkan has brought in past discussions, warnings can be problematic for some customers who elevate warnings to errors. Since a README isn't strictly necessary for private/internal package use, this could be a frustrating experience for those who don't need it.

The alternative is that we just print a "suggestion" or message as this would increase feature awareness without being overly aggressive. I decided not to do this for the initial release for a few reasons:

1. Customer feedback indicated interest in an overall package quality auditing experience which is aligned with @JonDouglas package quality indicators work. "Suggestions" will likely be apart of that work.
2. Our README support on NuGet.org is not at full parity with GitHub and may have some friction for customers to get their READMEs "NuGet.org ready." We should understand and remove these friction points as well as we can before pinging customers for not adopting READMEs.
3. Most client/pack validations today are private/public package agnostic. Customer's who are creating private packages that don't need READMEs have no way of disabling these suggestions.

2. Does this mean adding a README by default? I don't think we need to do that for the scope of this spec.

👍

3. The follow-up question here is that most readmes should generally be in the KB range & all resources for the README is hosted somewhere else like github content or another location. Will embedded readmes support this similar concept where outside resources can be accessed or will users need to embed those resources as well?

We will not support embedded resources for README images in this initial release. Allowlist --> proxy service is a more likely evolution, so size shouldn't be much of an issue. 1mb is a lot for text.