Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

x/pkgsite: surface module version release notes #42195

Open
mpx opened this issue Oct 25, 2020 · 3 comments
Open

x/pkgsite: surface module version release notes #42195

mpx opened this issue Oct 25, 2020 · 3 comments
Labels

Comments

@mpx
Copy link
Contributor

@mpx mpx commented Oct 25, 2020

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.

@gopherbot gopherbot added the pkgsite label Oct 25, 2020
@gopherbot gopherbot added this to the Unreleased milestone Oct 25, 2020
@mvdan
Copy link
Member

@mvdan mvdan commented Oct 25, 2020

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
Copy link
Contributor Author

@mpx mpx commented Oct 25, 2020

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
Copy link
Member

@mvdan mvdan commented Oct 25, 2020

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.

@jamalc jamalc modified the milestones: Unreleased, pkgsite/unplanned Oct 26, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
4 participants
You can’t perform that action at this time.