On 30.08.2013 11:48, Johan Corveleyn wrote: > On Fri, Aug 30, 2013 at 12:20 AM, Ben Reser <b...@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. br...@wandisco.com
