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

Update CHANGELOG.md to follow Common Changelog conventions #554

Closed
chuckwondo opened this issue May 1, 2024 · 5 comments · Fixed by #584
Closed

Update CHANGELOG.md to follow Common Changelog conventions #554

chuckwondo opened this issue May 1, 2024 · 5 comments · Fixed by #584
Labels
impact: documentation Improvements or additions to documentation

Comments

@chuckwondo
Copy link
Collaborator

In order to maximize the benefit of our CHANGELOG.md, I propose we update it to follow the Common Changelog conventions. In conjunction, we should find an appropriate location in our other docs to indicate that we are following these conventions, perhaps in our Contributing Guide.

@jhkennedy
Copy link
Collaborator

jhkennedy commented May 1, 2024

@chuckwondo, can you expand on why you prefer Common Changelog over Keep a Changelog? Reading through their comparison:
https://common-changelog.org/#62-how-is-this-different-from-keep-a-changelog

  • I'm neutral to positive on the additions
  • I like having less categories
  • I disagree on the no unreleased section as the upfront assumption is tied to a specific GitHub workflow and idea of "released", and in my opinion, subsections 1-3 are strictly not true.

@chuckwondo
Copy link
Collaborator Author

@chuckwondo, can you expand on why you prefer Common Changelog over Keep a Changelog? Reading through their comparison: https://common-changelog.org/#62-how-is-this-different-from-keep-a-changelog

  • I'm neutral to positive on the additions
  • I like having less categories
  • I disagree on the no unreleased section as the upfront assumption is tied to a specific GitHub workflow and idea of "released", and in my opinion, subsections 1-3 are strictly not true.

@jhkennedy, I think I'm pretty well in agreement with you here.

My preference for Common Changelog (not necessarily in its entirety, per the points you made above) is that it is much more descriptive/prescriptive on how to make good entries. Keep a Changelog has no such details, so it's not as much about the the differences noted above, as it is about having good guidelines on how to write good change entries, as well as anti-patterns.

I see at least a couple of options for us to consider:

  1. Follow the structure in Keep a Changelog, but refer contributors to Common Changelog for guidelines on how to (and how not to) write good entries.
  2. Follow Common Changelog, but note where we deviate, such as including an Unreleased section (per Keep a Changelog).

What say you?

@jhkennedy
Copy link
Collaborator

@chuckwondo, thanks for the answer! Either sound good to me -- I think it'd be easier for contributors to do (2).

@chuckwondo
Copy link
Collaborator Author

@chuckwondo, thanks for the answer! Either sound good to me -- I think it'd be easier for contributors to do (2).

Cool. Works for me!

@danielfromearth
Copy link
Collaborator

I'm gonna start making a first attempt at addressing this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
impact: documentation Improvements or additions to documentation
Projects
Status: Done
Development

Successfully merging a pull request may close this issue.

3 participants