Better release notes

Gregory Szorc gregory.szorc at gmail.com
Thu Feb 2 14:56:40 EST 2017


On Thu, Feb 2, 2017 at 11:46 AM, Augie Fackler <raf at durin42.com> wrote:

> 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.)
>

If you are referring to the poor usability of file merges with CHANGELOG
files, then perhaps this will inspire us to invent a feature that allows
repositories to declare which merge tool to use on various files. (We
already have a "union" merge tool for files like this but merge tools must
be explicitly configured in an hgrc or at run time. I think there is room
for e.g. a .hgmergepatterns file that behaves like [merge-patterns] and
allows in-repo declaration of merge tools so things "just work.")
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.mercurial-scm.org/pipermail/mercurial-devel/attachments/20170202/ff0908d0/attachment.html>


More information about the Mercurial-devel mailing list