[Releasing] [Development] Change file process & improvement proposal

[Edward Welbourne]

On Thu, Jan 26, 2017, at 01:28 PM, Kai Koehne wrote:
>> Anyway, this all feels like we get side-tracked in details. To reiterate:
>>
>> - We do (still) have a problem with our ChangeLog files
>>   * The quality of the entries, and the scope, greatly differs (between
>>   modules)
>>   * We do have a problem getting them in place on time for a release

Robin Burchell replied:
> Agreed. In the past, I've had to spend far too much time in "git log"
> digging up extra changes that should have been mentioned, but weren't.

Would it help if I put up an API review around the time folk are working
on change-logs - even when it's for a patch release - so that at least
the changes visible in API headers are easy to find ?  Or are the lost
changes too often elsewhere ?

>> Jani's proposal is to fix parts of this is to encourage committers and
>> reviewers to write [ChangeLog] entries as part of the commit. This could
>> be encouraged by
>> * Enabling the [ChangeLog] line by default in the commit template

> This seems reasonable, provided there's some guidance about how to use
> it properly.

... and that guidance is easy to find.  A search in our wiki for just
"ChangeLog" gets some change-logs, but no obvious guidelines; a search
for "ChangeLog guideline" gets nothing.  Thankfully a visit to
[[Category:Developing Qt::Guidelines]] found me
https://wiki.qt.io/Commit_Policy#Change_Log
which appears to be the best we have at present; it's very close to what
appears in the commit message template.

>> * Enforcing a [ChangeLog] entry by the Sanity Bot (under conditions xxx)

> Sounds good, although I'd suggest that starting off with a slightly
> softer mallet might be a good idea, at least as an initial transitional
> step. Maybe making it complain about a lack of ChangeLog tag, but not -1
> the change, to start encouraging better habits before they are later
> enforced. Thinking primarily here about existing pushed, but not merged
> changes. I don't have hard feelings about this, though.
>
> For "under conditions xxx", I'd just apply it to everything. Less
> difficult to get wrong, and more consistent :)

So: gripe about any commit without a ChangeLog.
That'll remind reviewers to think about whether one is needed.
Simple enough.

	Eddy.