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

defer to the GitHub releases page as the canonical changelog #48

Merged
merged 2 commits into from
Aug 12, 2020

Conversation

displague
Copy link
Member

@displague displague commented Aug 12, 2020

This PR updates:

  • CHANGELOG tracking
  • adds @displague as a codeowner
  • adds debugging tips

Changelog

The CHANGELOG.md file has fallen out of sync. The information tracked between this file and the GitHub releases page differed (before I synced them).

In order to ease the maintenance of the changelog, especially since goreleaser will maintain it with git commit information, we should defer to the GitHub releases page.

Goreleaser only lists the commit messages between releases. Maintainers should adjust the release notes (which is something they were doing anyway) to make it easier for users to understand what changed between releases at a high level.

I find that the automated release process, along with the human process of release notes editing, and the inclusion of a CHANGELOG.md that refers to the GitHub URL satisfy the concerns stated on Keep a Changelog:

What about GitHub Releases?
It's a great initiative. Releases can be used to turn simple git tags (for example a tag named v1.0.0) into rich release notes by manually adding release notes or it can pull annotated git tag messages and turn them into notes.
GitHub Releases create a non-portable changelog that can only be displayed to users within the context of GitHub. It's possible to make them look very much like the Keep a Changelog format, but it tends to be a bit more involved.
The current version of GitHub releases is also arguably not very discoverable by end-users, unlike the typical uppercase files (README, CONTRIBUTING, etc.). Another minor issue is that the interface doesn't currently offer links to commit logs between each release.

@displague displague merged commit a4be461 into equinix:master Aug 12, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

1 participant