On Fri, Aug 30, 2013 at 1:01 PM, Branko Čibej <brane_at_wandisco.com> wrote:
> 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.
It would not be a requirement, just optional (just like we don't
require every commit to have a corresponding entry in CHANGES).
Re. the describing twice: that's already the case currently, except we
describe them twice in two different places (once in the log message,
and once in CHANGES), and often with much time in between and by
different people (which makes it more fragile IMO).
On top of the message for developers ("describe what changed in the
code, and why"), you get an additional line of comment targeted
towards users (which can be formulated quite differently).
> 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.
Wouldn't that almost the same as my suggestion, just that you split it
accross two places (log message and CHANGES file)? I don't think
that's better than putting it right there in the log message, where it
can be extracted by a tool into any CHANGES file that has this commit
backported.
In fact, when you put it in the log messages, you might not even have
to keep a CHANGES file in version control (except perhaps for the
manual post-processing -- though perhaps you could also put those
edits directly in the "sources", i.e. the log message).
Anyway, it's just an idea. It's not perfect, but I've seen it work
quite well in practice.
--
Johan
Received on 2013-08-30 13:20:28 CEST