Re: Improving CHANGES (or at least making it easier to produce)

On 30.08.2013 11:48, Johan Corveleyn wrote:
> On Fri, Aug 30, 2013 at 12:20 AM, Ben Reser <ben_at_reser.org> wrote:
>> Right now we produce the CHANGES file by someone going through the log and
>> looking at the individual commits and coming up with the entries for CHANGES.
>> It's an after the fact process.
>>
>> The problem with this is that it's not always obvious from commit messages what
>> the user impact is. I could probably find some examples but I'm not going to
>> bother to pick on anyone in particular. Ultimately, our commit messages are
>> for developers and the CHANGES entries are for users. There's a wide gap
>> sometimes between what goes where.
>>
>> So I'd like to suggest that we start including a Changes field in the STATUS
>> file entries. I haven't exactly worked out the details so nobody needs to rush
>> out right now and start doing it immediately.
>>
>> Since the people proposing the backport and the people voting for it usually
>> have the best idea of the impact it should improve the quality of our CHANGES file.
>>
>> If a STATUS entry doesn't require a CHANGES entry (e.g. improvement to an
>> already merged change that wasn't released yet) then we can just ommit this
>> line. I can then simply search through the commit logs (since the backport.pl
>> includes the STATUS entries in the commit log when it commits) and find all the
>> CHANGES entries.
>>
>> It'll still take some editing for consistency and style probably. But it'll be
>> a lot better in my humble opinion.
>>
>> This of course does nothing to help producing the CHANGES file for a 1.x.0
>> release, because there are tons of changes going on trunk that do not ever get
>> backported. A huge thing that can help there is to start trying to describe
>> why a user would care about the commit and not just a developer. This is
>> something that I think we all can put a little bit more effort into on our
>> trunk commits that'll help us when we produce 1.9.0.
> Here is an alternative approach, that addresses both problems (CHANGES
> for backports, and CHANGES for next big release), and it's the way we
> currently do this at my workplace:
>
> Put the information for end-users directly in the commit message which
> makes the change (or one of the commit messages if there is a whole
> series of related commits), encoded in some parseable way. That way a
> release tool can extract this information and construct a draft of
> CHANGES (which can then still get final edits).
>
> This avoids duplication of information over both STATUS and other
> places (the description of the change is usually the same for trunk
> (next 1.x.0 to be) as for backports). At the cost of the developer who
> commits the change having to think, at that point, about how one would
> phrase this for end-users (but this is probably the best time (and the
> best person) to think about this -- and if need be, it can always be
> added after the fact to the log message). As an added bonus, the
> user-facing message is then also immediately there in the log message,
> which can be handy for devs looking through a file's history.
>
> At my workplace, we have a convention (enforced by pre-commit hook) to
> use a prefix between square brackets ([U] for the user-facing text,
> [S9] for the developer details (our team is called the "system9" team)
> -> which also get extracted to another text file for an overview of
> all the dev-messages of a single release). Here we could use something
> similar to the contribulyzer syntax (for instance "Change: blablabla
> (issue #1234)").
>
> Any revision numbers that are related to such a "change" can maybe be
> extracted automatically (for inclusion in the CHANGES, if there is no
> issue number mentioned). "Change" entries which are identical (same
> Change in 10 different commits) would of course be folded into one
> line in CHANGES.

I'm a bit confused by the idea that you'd require a log message to
describe a change twice. Doesn't make much sense to me at all.

A log message should describe what changed in the code. Automatically
generating release notes and/or CHANGES from log messages is, in my
experience, quite impractical. A better approach would be to require the
CHANGES file to be updated in the same commit as the actual relevant
change. But even that's not realistic, because often such a change will
be split across several commits -- or, for example, developed on a branch.

-- Brane

-- 
Branko Čibej | Director of Subversion
WANdisco // Non-Stop Data
e. brane_at_wandisco.com