Update CHANGELOG.md to follow Common Changelog conventions

[chuckwondo]

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]

@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]

@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]

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

[chuckwondo]

@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]

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