[Development] ChangeLogs

[Oswald Buddenhagen]

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.

also, sergio is now attempting to make 5.0.1 changelogs in a heroic
one-man-effort - not entirely surprisingly, this turns out to be a tad
more tedious than planned.


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.

this mechanism won't work any more without modification: CI makes the
integration turnaround time too long, and thus the conflicts unbearable.
a workaround would be maintaining pending ChangeLogs in a wiki, and
putting them into git right before the releases. i think this can work
in principle. a bit of a problem is determining who "owns" a change -
the contributor (who can be a drive-by contributor who just happens to
be never seen when it's time to update changelogs, and doesn't want to
create a wiki account to start with), or the approvers (which one of
them?). such unclear responsibilities tend to produce poor results
(c.f.: current situation).


what sergio attempted now: mostly automated changelog generation from
the commit summaries. this failed spectacularly: the log contains way
too many useless entries, and many entries are meaningless. the main
problem is that the commit summaries are (rightfully) written from a
code change perspective, while the changelog needs to be user-oriented.
redacting this by hand by a single person is No Fun ™ for a patch
release, and outright insane for anything bigger.


two more approaches have been previously proposed:

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

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.


regards