[Development] ChangeLogs

[Thiago Macieira]

On quinta-feira, 17 de janeiro de 2013 16.05.40, Oswald Buddenhagen wrote:
> hi *,
> 
> as some certainly noted, the completeness of dist/changes-* severely
> deteriorated over the last few minor releases, and in particular 5.0.0
> is one of the poorest qt changelogs seen in a while.

Qt 5.0.0 is also one of the most major releases seen in a while -- 7.5 years 
to be precise. The major release deserves special treatment: we agreed on 
listing what was important for the porting effort.

> 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.

> 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.

> 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.

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 190 bytes
Desc: This is a digitally signed message part.
URL: <http://lists.qt-project.org/pipermail/development/attachments/20130117/cd59a53e/attachment.sig>