Better release notes

[Augie Fackler]

On Thu, Feb 2, 2017 at 2:21 PM, Siddharth Agarwal <sid at less-broken.com> wrote:
> On 2/2/17 10:53, Gregory Szorc wrote:
>>
>> * Checking in a dedicated file tracking release notes and starting a
>> culture where we update this file accordingly (many open source projects do
>> this)
>
>
> This is a good idea. +1 for a changelog file that explicitly only contains
> user-facing release notes.
>
>> * Adding special syntax to commit messages to facilitate release notes
>> auto generation. This would have to support multi-line notes for detailed
>> descriptions. This is like what we do today except in my head I think the
>> notes would be derived not from the summary line but from special syntax
>> elsewhere. We could enforce that certain commit messages have certain
>> syntax. e.g. a "(BC)" message would require a special section detailing what
>> the compatibility change is. We could also e.g. introduce a "(FEATURE)" in
>> the summary line that indicates a new feature and requires syntax to
>> describe a user story, how to use it, etc.
>
>
> Commit messages are immutable and hard to copy-edit once they're in the
> repo, so -1 on this.


Kevin and I have been trying to figure out a better approach to
release notes. I'm kind of bummed out by the idea of a
manually-curated changelog, but would be enthusiastic about some sort
of hybrid approach: a section in the commit that could auto-populate
part of a better changelog at release time, along with other
interesting points extracted automatically from commits. Thoughts?

(I don't mean to say "don't do a CHANGELOG" file, but instead hope we
can find something that's a better usability win overall.)