Improve changelog readability

[dnsl48]

Overview

The current changelog format is less than optimal. Here's an example: CWP 2.6.0 Release.

Although "security", "features" and "bugfixes" sections are manageable to read, it's still not clear what is going on there, without looking into the linked commits. E.g.:

• 2020-01-13 81d466e support JSON encoded identity data for ASSERT (Dylan Wagstaff)

The message explains the change well, but without the module context it is baffling (RealMe). When it comes to "Other changes" section, there's too much going on and it is hard to find any valuable info by glancing at it.

Proposal

• [ ] Implement https://github.com/silverstripe/cow/issues/139 (add info about modules)
• [x] Add new commit prefixes: RFC-9687

Notes

• Some parts of the functionality may be related with https://github.com/silverstripe/cow/issues/184
• Here is an example of the grouped changelog (with release plan included):
  • Option A (plain): https://gist.github.com/dnsl48/946e812827c06ce2c14548c63c1023ce
  • Option B (tables): https://gist.github.com/dnsl48/f69d1c007566729a65f2ab174403bfae

PRs

• [x] https://github.com/silverstripe/cow/pull/188 (RFC-9687 Commit Prefixes)
• [x] https://github.com/silverstripe/cow/pull/190 (Twig3)
• [x] https://github.com/silverstripe/cow/pull/191 (changelog format)

Follow up TODO

• [ ] Update release documentation (document changelog--audit-mode flag usage)

[dnsl48]

/cc @silverstripe/core-team

[brynwhyman]

Not that we're necessarily limited to what can be done here, but of the suggested points in the proposal my thoughts are this is the most important as there's a lot of clutter there:

Add new commit prefixes for Continuous Integration related commits (RFC tbc)

Plus, as discussed an additional heading for the DOCS prefix would be nice.

Aside from that, I really like the idea of #184 and would prioritise that over making the CWP changelog more readable. Given the CWP changelog includes the entire kitchen-sink, I don't feel like it's an optimal list to refer Developers to? Where possible, the module repository could be referred to as the source of truth

Perhaps we could discuss with CWP Developers the usefulness of using the CWP changelog page to include commits for cwp/cwp-recipe-core and cwp/cwp-recipe-cms and otherwise list the new module versions and GitHub changelog links (assuming #184) contained in the release?

[dnsl48]

Given the CWP changelog includes the entire kitchen-sink, I don't feel like it's an optimal list to refer Developers to?

One source of truth for all the modules is very important nonetheless. It's just impossible for devs to check out 100 different places to see every module own changelog when a release is out.

[brynwhyman]

Fair point 😄

[robbieaverill]

I think this issue highlights the importance of writing succinct and descriptive commit messages

[Cheddam]

Whoops, this shouldn't be closed until all three PRs are merged!