[Development] ChangeLogs

[Koehne Kai]

> -----Original Message-----
> From: development-bounces+kai.koehne=digia.com at qt-project.org
> [mailto:development-bounces+kai.koehne=digia.com at qt-project.org] On
> Behalf Of Thiago Macieira
> Sent: Thursday, January 17, 2013 4:49 PM
> To: development at qt-project.org
> Subject: Re: [Development] ChangeLogs
> 
> > [...]
> > first a bit of historical background: in The Good Old Trolltech Days
> > ™,
> > *every* developer was compelled to write changelog fragments for their
> > own commits before the release.
> > this was assisted by a somewhat primitive commit log browser with a
> > checkbox next to each entry, which created a prototypical changelog
> > entry for each checked commit.
> 
> I don't think it did that. The checkbox was only an aid to let you know
> whether you had reviewed everything. And for the release manager to know
> whom to bug about not having done their changelogs.

Anyway, most Qt committers were working full-time in one company. Times are different now, we're many more, a lot not working full time on Qt, so just asking all the committers to fix the log before a release doesn't really work out any more, even if we had a tool like above for git.

> > we introduce a new footer ("ChangeLog:") to commit messages. this
> > would shift the burden to the contributor, and it could be properly
> reviewed.
> > the generation the logs could be fully automated, and only minimal
> > redactional work would be necessary.
> > a (somewhat minor) downside would be some redundancy in the commit
> > messages.
> > don't suggest to change the style of the commit summaries to be
> > ready-made changelog entries - this would be neither without
> > disadvantages (different target audience), nor would it fully solve
> > the problem (selection of commits for the changelog).
> 
> I don't like writing it in the commit message because it clutters the message
> with redundant information. Maybe we should consider git notes -- if Gerrit
> can propagate them.

If git notes would be seamlessly integrated that might work out indeed. But honestly speaking I don't think an additional line in some important commits does hurt too much either ... Often enough the commit message might actually be != the changelog entry != the JIRA task, because all of them have different audiences & purposes.

Anyway, if I understood Ossi's second mail right the message would in a final system not even be part of the git log any more.

> > an alternative would be auto-generating the changelog from jira tasks.
> > consequently, if you consider something important enough for a
> > changelog entry, you need to create a task for it if there is none
> > yet. i guess some metrics guys would looooove that idea, too. for
> > developers, it's of course additional work.
> 
> But not by much. This would be acceptable, provided that generating such a
> draft changelog isn't too difficult.

I personally wouldn't go the JIRA route. I consider changing the title and the text of a user's bug report by myself impolite, and asking the original reporter to fix it , split things into different tasks etc just for the sake of a clean commit log is also not very appealing. 

So I'd go for adding a 'Commit-log:' message to the git, with the potential extension of extracting it in gerrit later on.

Regards

Kai


> --
> Thiago Macieira - thiago.macieira (AT) intel.com
>   Software Architect - Intel Open Source Technology Center