x/pkgsite: surface module version release notes

[mpx]

I review module release notes to decide whether I should upgrade a particular module now, later, or maybe never.

There is currently no standard way to represent release notes for module versions in the Go ecosystem (commit logs are a poor substitute for the first pass). Developers need to hunt around to work out how a particular module provides release notes (if at all). Eg:

• Github release notes (eg, gRPC), or via some other hosting provider
• Changelog, CHANGES, and/or NEWS files
• README sub-section
• Separate project website
• ...
• Commit logs

Ideally there should be a simple, integrated way for module authors to make their release notes available on pkg.go.dev. For example, pkgsite currently integrates README.md (very useful). The version page (eg, https://pkg.go.dev/google.golang.org/grpc?tab=versions) could highlight actual changes for each version which quick links to jump to a particular module.

Providing a standard way (eg, file/format) for describing module version changes via pkg.go.dev would incentivise the community to adopt a single standard. This would make it a little easier for developers to decide which module or module version they should use. Good release notes might even be considered an indicator of module health.

[mvdan]

There already is a standard for changelog files, which we could piggyback on: https://keepachangelog.com/en/1.0.0/

If a project uses another form of changelog, such as GitHub Releases or a custom HTML page, we could simply link to the page instead of trying to understand or render the information.

I understand that GitHub Releases are perhaps more widespread than CHANGELOG.md, but it's worth pointing out that the former is non-portable and can't be obtained as part of a vcs clone or module zip, so it's significantly less useful to pkgsite and users, I think.

[mpx]

Yes, I definitely think any changelog should be part of the module and not tied to a particular web service.

https://keepachangelog.com looks reasonable, but I couldn't see if it was commonly used somewhere. I left it out above since I think it's more important to have a standard way, than to have any specific standard (see gofmt 🙂).

[mvdan]

I do use it for a couple of projects, as far as I know it's the only well documented standard :) So I do think there's an advantage in reusing it rather than designing our own standard.

[codyoss]

Since module are tag based I wonder if release notes could come from the tag message if there is one provided.

[hu3bi]

I highly like this proposal.
Was thinking of proposing the same thing myself, that's how I found it.