Better release notes

Gregory Szorc gregory.szorc at gmail.com
Thu Feb 2 18:53:31 UTC 2017


Every Mercurial release, I create a curated summary of the release notes to
distill to Mozillians. As part of doing this, I realize that the official
release notes are not very "user friendly" and oftentimes incomplete. This
especially holds true for https://www.mercurial-scm.org/wiki/WhatsNew,
which contain a lot of entries that quite frankly aren't relevant to most
end users. The ReleaseX.Y pages (e.g.
https://www.mercurial-scm.org/wiki/Release4.1) are better, but they rely on
humans to keep populated (and we often forget).

I'd like to start a conversation around making the release notes more
friendly to end-users.

I think some of the goals should be:

* Call out major new features, preferably with a user story around them
* Prune out changes not relevant to end users
* Actually document minor new features (e.g. "patch: add label for coloring
the index extended header" in WhatsNew is nearly meaningless because it
doesn't say what that label is)

Some ideas for this include:

* Checking in a dedicated file tracking release notes and starting a
culture where we update this file accordingly (many open source projects do
this)
* 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.

Thoughts?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.mercurial-scm.org/pipermail/mercurial-devel/attachments/20170202/2908c9bf/attachment.html>


More information about the Mercurial-devel mailing list