[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: Johan Corveleyn <jcorvel_at_gmail.com>
Date: Mon, 4 Dec 2017 22:45:09 +0100

On Mon, Dec 4, 2017 at 3:15 PM, Julian Foad <julianfoad_at_apache.org> wrote:
> Stefan Sperling wrote:
>>
>> Johan Corveleyn wrote:
>>>
>>> The intention is that the RM doesn't need to go through all the full
>>> log messages in detail, but that he can trust the output of
>>> write-changelog, combined with trust in the quality of the log
>>> messages involved.
>>
>>
>> OK, in that light it all makes sense and I agree this is worth a try.
>> And if we don't manage to pull it off well enough, nothing is lost
>> compared to the status quo.
>
>
> Johan, you told us at the hackathon (and mentioned in the older linked
> thread) that your team has been using a system like this for some time at
> your workplace. For me, that gives the suggestion a lot more credibility.

Yes, absolutely. We're using a similar method for over 15 years now,
with weekly releases of a big software system (healthcare software,
being used in around 20 Belgian hospitals). It's more strict /
structured than what I've proposed here, but that's normal I guess ...
corporate world vs. open source. And it's not perfect of course, but
it has served us well and saves us a lot of time. I'm trying to find a
pragmatic way to apply the same core idea and get the benefits of "all
committers writing their own changelog entries at the time they're
writing the code".

...
> In the case where a user-facing but very simple change is made, I think we
> would only need to write the tagged user-facing line in the log message --
> we should never need to write two lines that say the same thing. Example log
> message:
>
> [[[
> * subversion/svn/svn.c:
> [U:client] Add a 'reintegrate merge' section to the 'svn help merge'.
> ]]]

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:

[[[
[U:client] Add a 'reintegrate merge' section to the 'svn help merge'.

* subversion/svn/svn.c:
  (blah): Add help text.
]]]

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:
[[[
@U:client Add a 'reintegrate merge' section to the 'svn help merge'.

* subversion/svn/svn.c:
  (blah): Add help text.
]]]

or
[[[
* subversion/svn/svn.c:
  @U:client Add a 'reintegrate merge' section to the 'svn help merge'.
]]]

or as a suffix:
[[[
* subversion/svn/svn.c:
  Add a 'reintegrate merge' section to the 'svn help merge'. [U:client]
]]]

Just thinking out loud here ...
Or we put it at the bottom as an "extra", like the contribulyzer
lines, but then we have the problem of potentially having to write the
same line twice:
[[[
* subversion/svn/svn.c:
  (blah): Add a 'reintegrate merge' section to the 'svn help merge'.

[U:client] Add a 'reintegrate merge' section to the 'svn help merge'
]]]

Hmmmm

> I think one of the keys to making this successful is to keep the burden low.
> For example, if "[U:section]" is the general tag for a user-visible change
> then just "[U]" should be allowed so the dev can go ahead with the commit
> when a suitable section is not defined or not obvious.

Yes, good idea. Anything with [U] would become a simple '*' bullet
below "User-visible changes", and the RM can decide where it goes.

-- 
Johan
Received on 2017-12-04 22:45:35 CET

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

This site is subject to the Apache Privacy Policy and the Apache Public Forum Archive Policy.