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

On Tue, Dec 5, 2017 at 1:00 PM, Branko Čibej <brane_at_apache.org> wrote:
> 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.

I'm not sure. I think we're very much accustomed to a certain style
for CHANGES, and another style and information-density for the summary
of commit messages. If these could converge, then sure, this could be
a good idea. If not, I think we haven't gained much (the RM would have
to rephrase them all anyway).

For example, CHANGES for 1.10 contains (just taking a couple of
entries under User-visible "Minor new features and improvements"):

    * New '--file' option for several svnadmin subcommands (r1738021)
    * ra_serf: Adjustments for serf versions with HTTP/2 support (r1716400)
    * windows: Correctly check result from LoadLibrary() call (r1755983)
    * FSFS: Open transaction's proto revision in write-only mode (r1759135)

And the corresponding lines out of "./release.py write-changelog
--pocfirstlines trunk tags/1.9.7" are (just grepping on the revision
numbers):

    * Introduce `--file' option for svnadmin dump, dump-revprops, load
and (r1738021)
    * Apply some minor tweaks to libsvn_ra_serf to handle some http/2
cases. (r1716400)
    * Correctly check result from LoadLibrary() call: LoadLibrary()
returns NULL (r1755983)
    * FSFS: Open transaction's proto revision in write-only mode.
Read/write mode (r1759135)

That last one is actually the same, nice :-).

I think these could converge, i.e. we *can* get used to write our
summaries in the CHANGES style (for instance: put the relevant
"component" in front, like "ra_serf:", "windows:", ...; and make the
first line of the summary shorter). But it'll take getting used to
:-).

Another thing is that there are a lot more commits than entries in CHANGES.
* CHANGES for 1.10 is currently 244 lines.
* output of "./release.py write-changelog --pocfirstlines trunk
tags/1.9.7" is 1633 lines.

That means we'd have to use the "#" (or other symbol) escape a lot.
That, or a lot of those commits are reverts (we'd need to handle these
well in any case), or are summarized with "(... et al)".

The flip side would be, if we could get the hang of this, we'd need no
special syntax, no duplication of "almost the same text", and our
"commit message summaries" are automatically fit for CHANGES (and it's
safer to forget to exclude a commit). Which also means an option for
"svn log" showing only the first line would be interesting, and would
approximately yield CHANGES plus the "#-escaped" summaries.

Hmmm, red pill or blue pill.

-- 
Johan