[Development] ChangeLogs

[Knoll Lars]

On Jan 29, 2013, at 1:31 AM, Alan Alpert <416365416c at gmail.com> wrote:

> On Mon, Jan 28, 2013 at 4:21 AM, Jason McDonald <macadder1 at gmail.com> wrote:
>> On Fri, Jan 18, 2013 at 1:05 AM, Oswald Buddenhagen
>> <oswald.buddenhagen at digia.com> wrote:
>>> 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.
>> 
>> I was quietly wondering to myself how long it would take for someone
>> to notice that I stopped acting as editor for the changelogs when I
>> left Nokia.
>> 
>> As Sergio has no doubt discovered, manually generating the changes
>> file is a tedious and time-consuming process, particularly when the
>> level of co-operation from developers is low to non-existent.
>> 
>> [...]
>> 
>> So, based on my bitter experience, here are my recommendations:
>> 
>> 1. Let's acknowledge that writing the changes file is going to have to
>> be a manual process due to the complexity of the decision-making and
>> the lack of a strict development process.
> 
> Yes, it will have to be an ultimately manual process. But I like how
> your later suggestions provide hope that tools and processes can make
> the manual part easier.

Agree. I can't really see a way to automate this neither.
> 
>> 2. Let's agree that module maintainers should be responsible for their
>> module's changes file, and clearly document that responsibility on the
>> part of the wiki that lists a maintainer's duties.
> 
> +1. Release manager would still be responsible for chasing them up though ;) .
> 
>> 3. Let's call for volunteers to prototype a new changelog tool along
>> similar lines to the old one, but this time with a better UI, the
>> ability to share data between users via a git repo, and some kind of
>> checklist to assist the decision-making process.  I'm happy to help
>> with setting requirements, but I regret that I won't be able to do
>> much more than that as my new full-time job does not involve Qt.
> 
> I'd start playing around with a QML prototype (nothing I love better
> ;) ) but requirements like "better UI" are too vague to even get
> started. Especially since I can't recall what the old Trolltech tool
> looked like. Could you flesh out initial ideas a little more, so
> potential volunteers could prototype their prototype?

The old Trolltech tool was nothing more then a list view showing all the perforce changes between two revisions. Clicking on a change set would show you the detailed description and diff in a view on the right (a bit like gitk).

It had a checkbox, so you could mark a particular change as processed, and it would store this locally. This allowed you to do the work in chunks and you would at least always know what you've already processed. IIRC, you could also limit the change sets you were interested in to a certain directory/set of files.
> 
>> 4. Let's try to make the job of our maintainers that little bit easier
>> by writing good commit summaries and diligently reviewing the commit
>> summaries of our peers.
> 
> +1, but I think the tool is a more realistic way of making the task
> easier for the maintainers.

Yes, I remember that the Trolltech tool, simple as it was, was a tremendous help.

Cheers,
Lars