Always put a topic in your change summary (was Re: [PATCH] remove template-vars.txt)

Matt Mackall mpm at selenic.com
Thu Aug 30 16:06:18 CDT 2012


On Thu, 2012-08-30 at 01:49 +0200, Mads Kiilerich wrote:
> Matt Mackall wrote, On 08/29/2012 10:12 PM:
> > I spot 7 failures to conform to ContributingCode in the top 10 commit 
> > summaries on this page: 
> > http://hg.intevation.org/mercurial/crew/graph/573e80049cad
> 
> In 'hg log -u mpm -l 20' I spot 16 failures to conform to the 
> 'subsystem:' part of ContributingChanges. They are all that way for a 
> good reason: There is no 'subsystem' for these changes.

Bah. Yes, there are a ton of merges (in the de facto merge style) and
one tag (with the default message) that don't "conform". But none of
them are subject to being "contributed changes" to start with: you can't
mail me a merge or a tag.

> I spot no explanation on ContributingChanges of what 'subsystem' should 
> be for commits that don't touch a specific subsystem - and shouldn't be 
> mentioned in WhatsNew.

Make something up. I don't actually care, so long as it's even vaguely
meaningful.

But don't intentionally make a bunch of counterexamples to the rules I
remind people of every single day and push them to crew without
discussion and expect me to just grumble and pull them because it's a
nuisance not to. That's not cool.


That said, I'll clarify why the subsystem marker exists. You're right,
the original motivation is preparing release notes, but the reason it
helps there applies everywhere. Before the standard form, when
constructing the release notes, I'd have to read and understand each
summary to categorize it. I'd say that just the parsing and
contextualizing takes a few seconds per line. In practice, to sort the
changelog, I might have to read each line a few times at different
stages of the process, possibly cutting and pasting it a few times as
well. So sorting and filtering several hundred changes could literally
take hours. So annoying.

With the subsystem tag, I can do some first-pass mechanical sorting and
filtering that eliminates something like two-thirds of the work. And the
remaining work is much easier because the context of each summary is
right there in the first word and closely-related changes get clumped
together. And if it's something like "typos:" or "cleanups:" (things
other people have used), then I can short-cut the process. Five cleanup
patches in a row? Chomp.

But as it happens, that short-cut is not just useful for me, it's useful
for anyone who browses or searches the log. Looking for a change that
affects merging? Then you can ignore all of these changesets start with
"hgweb:" and "doc:" without reading more than the first word. And that
one marked "merge:"? We should probably look closely at that one.

I've changed "subsystem" to "topic" on ContributingChanges to make it
clear that it's really in no way tied to the structure of the source.

(For the archaeologically-minded, the output of the following suggests
that this rule became the predominant style in mid-2007:

$ hg log -M --template '{desc|firstline}\t{date|isodate}\n' | perl -pe
's/^(.*: )/ $1/'

..though instances of it go all the way back to commit 35. It was first
documented as a submission guideline on the Wiki, complete with the idea
that it simply needs to be an abstract topic, in Aug 2010:

  The first line should be like ''<command/module/topic>:
  <short   description> (optional issue number)'', no more
  than 80 characters in total, and followed by an empty line.

http://mercurial.selenic.com/wiki/ContributingChanges?action=diff&rev1=31&rev2=32

..by Mads Kiilerich!)

-- 
Mathematics is the supreme nostalgia of our time.




More information about the Mercurial-devel mailing list