search

NuGet / Home

Repo for NuGet Client issues
Other
1.49k stars 249 forks source link

Make Release Notes field more usable #1734

Closed NickCraver closed 8 years ago

NickCraver commented 8 years ago

In short: I propose making the Release Notes field markdown, or at the very least have nuget.org atuomatically convert URLs into hyperlinks in the field. Right now the breakdown of the top 50 packages on nuget.org is:

It's tedious to maintain both a changelog in a repo as well as in all packages (note: this may include multiple packages for a single repo, multiplying the pain). I feel that's supported by the 90% above with no notes in NuGet. What is doable is maintaining one copy of changes - which means linking to it is very appealing, evidenced by the 24% above (many of which are Microsoft packages).

I'd like to throw out the following options as suggested fixes:

  1. Make the field markdown (and nuget.org convert/render it properly) - this makes it much more useful overall.
  2. Auto-link URLs in release notes - so if you use it as a field it effectively becomes a link.
  3. Add a ReleaseNotesLink-like field specifically for a URL.
  4. Change the rules on the schema, and indicate if the field is a URI, it'll be rendered linkified.

For the curious, here's the entire top 50 list:

mgravell commented 8 years ago

Note the issues of text release notes is further complicated by the fact that it needs to be written in xml (*.nuspec) or json (project.json - in which case it also bloats the project file). As a fifth suggested fix:

5: make "nuget pack" and the dnx (project.json) tools allow a release releaseNotesPath field (separate to releaseNotes) which is a relative path (from the *.nuspec or project.json) to a text file that contains the release notes, which can be maintained separately. This could potentially be combined with option "3" above, such that:

As a stretch-goal incorporating idea "1" above, all mentions of "text file" above could be extended to mean "text file copied as-is, or .md file processed via your choice of markdown processor".

mgravell commented 8 years ago

As a side note: consumers do actually care about release notes. The moment I failed to update them (because I was experimenting with the new dnx build tooling, at a time when release-notes weren't supported), I got called on it: https://github.com/StackExchange/dapper-dot-net/issues/348

csharpfritz commented 8 years ago

I like this discussion, and believe that we need to revisit how release notes are surfaced to the package consumer. The idea of a releasenotes.md file in the package has been raised before, and I think we need to be careful about how to introduce this feature without breaking older clients.

yishaigalatzer commented 8 years ago

This is a duplicate of https://github.com/NuGet/Home/issues/1203, added notes to the other issue, to make sure we handle both of them as one.

ashmind commented 8 years ago

To add to @mgravell's suggestion, the way I would love to see it would be:

"releaseNotesPath": "README.md#Release_Notes"

so basically a section getting cut out of md file.

I would also like to see the same for description, as project.json is not very convenient for description editing.