Better release notes

Gregory Szorc gregory.szorc at gmail.com
Fri Feb 3 00:20:49 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.)
>

Augie pinged me on IRC and said to check out
https://github.com/hawkowl/towncrier.

Basically, there is a directory of files and file extensions describe the
change type (e.g. feature, bug fix, docs). Periodically, a command
aggregates all the "loose" "news" fragments into a centralized
changelog-type file, deleting the loose files along the way.

It is an interesting idea. It could probably be worked into our patch
submission mechanism: patches would contain a relevant "news file" (if
appropriate) and queuing changesets would rewrite them such that the
"loose" "news file" would be rolled into a central changelog.

Of course, this mechanism is only semantically different than adding
special syntax to commit messages and moving commit message segments to a
changelog file as part of queuing.

If we're talking about short-lived vehicles for storing "news fragments," I
think commit messages are the better home. It is easier to rewrite commit
messages than to maintain files. And the point of commit messages is, well,
to describe changes, which is also what a changelog file does. So I'm not
convinced that standalone files are necessary. Also, we have to consider
the patch-submitter experience. For evolve users, rewriting the changeset
will "just work" and your client will recover from news file deletes when
you pull from hg or hg-committed. But for non-evolve users, rebasing your
local changesets on top of the rewritten changesets (that deleted
individual news files) will leave a changeset adding a news file (instead
of an empty changeset that is dropped). So the experience for non-evolve
users is better if commit messages (as opposed to files) are used to hold
"news fragments."

So, perhaps we're looking at a hybrid model where incoming patches have
"news fragments" in commit messages (using a special syntax) and queuing
(or publishing) extracts this content to a standalone changelog file. That
would leave a standalone file that can be edited any time while preserving
the ease and convenience of declaring things in commit messages alone.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.mercurial-scm.org/pipermail/mercurial-devel/attachments/20170202/0cf478b2/attachment.html>


More information about the Mercurial-devel mailing list