Better release notes

[Sean Farley]

timeless <timeless at gmail.com> writes:

> Sean Farley wrote:
>> I assume that these commit messages were from employees with commit
>> access? If that's true, then that's a bit different than patch-based
>> review where we can edit and review the commit message / notes.
>
> Well, we had two sources:
> 1. Mozilla upstream, where in theory messages were curated, but
> possibly too technical to be useful to our audience
> 2. In house, where people had commit access, and while we could have
> tried to review, practically the pace prevented anything useful -- and
> I was the primary native speaker, my colleagues weren't native
> speakers.
>
> But note: even for Mercurial, getting commit messages to be great is
> hard. At this point I tune in once every couple of weeks and batch
> read, typically long after code has landed.
>
> For Cordova, where I think >50% of committers were native speakers,
> and where we had PRs, and comments, the commit logs weren't good
> enough for Release notes either. So, expecting to rely on commit
> messages as a final truth isn't a great idea.
>
> As a side note: I'm currently running my spelling checker against
> dozens of open source projects, and one of the portions with the
> highest spelling error rate is changelogs/commit messages.

Some good points there. Though, I didn't think we were talking about the
commit message in general but rather with the special note tag:

summary: change foo to bar

Some technical details. More blah werd.

:: notes

  This would be a highly curated message. Almost as if it were a patch
  in its own right.