[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: [PATCH] release.py: write-changelog function (POC)

From: Branko ─îibej <brane_at_apache.org>
Date: Tue, 5 Dec 2017 13:00:09 +0100

On 04.12.2017 23:01, Julian Foad wrote:
> Johan Corveleyn wrote:
>> [...]
>> Hm, yes, I agree with the "don't write the same thing twice". But
>> perhaps the "general description" above the list of affected files
>> would be a better place:
> [...]
>> Though, indeed, we're not required to always have a "general
>> description", and can just start with the affected files, if the
>> change is simple. So ... not sure.
>> That's the thing I'm most uncertain of at the moment: how to fit this
>> scheme precisely into our current log message style, without
>> interfering too much, keeping them as readable as possible for human
>> readers.
>> Maybe a syntax with '@' would be better, like annotations in Java or
>> doxygen. Like:
> [...]
>> or as a suffix:
> [...]
>> Just thinking out loud here ...
> [...]> Hmmmm
> Now you're over-thinking it. What you said first, what you use at
> work, is fine. Run with it!

IMO the important thing is to make the tagging in the log messages as
human-friendly as possible. That's what made the contribulyzer work so
well: there were no $[@foo;\\} syntactical quirks to remember and the
syntax is permissive.

Therefore I think stsp's suggestion of just taking the summary line in
the log message as the CHANGES entry is more likely to produce useful
results than any magic tagging. I don't think it's all that important to
classify the change into user-facing, etc., at commit time. All we need,
IMO, is a way to signal whether the change is or is not important.

So I'd suggest we use stsp's proposal with a small difference: by
default, every log message that has a summary line is important. If it's
not, start the first line with a # to tell the script to ignore it. That
way, it takes extra thought and effort to exclude a commit from the
CHANGES summary, which is IMO preferable to having to put in extra
thought and effort to have it included. It's easier to prune unnecessary
entries from the summary than it is to dig into commit history to find
the missing ones.

-- Brane
Received on 2017-12-05 13:00:14 CET

This is an archived mail posted to the Subversion Dev mailing list.