[Development] Changelogs for 5.3.0

[Thiago Macieira]

Em qua 23 abr 2014, às 09:04:35, Giuseppe D'Angelo escreveu:
> And no, commit message and changelog can't use the same rules. A
> commit message is usually in the imperative mode, present tense ("Fix
> foo"), and uses pluralis maiestatis + indicative in the body ("We do
> this, but we should do that, so this commit fixes it"). A changelog
> uses indicative past simple ("Fixed foo"), or passive present perfect
> ("Foo has been fixed"), and in general privileges an impersonal form
> ("It is now possible to use foo"), all of which indicate that the
> change has already happened in the past.

To be clear: there are two different audiences here.

The main commit message is intended to other Qt developers, notably the 
reviewers and your future selves. It's intended to explain *why* the change 
was made and why this particular change, as opposed to other possible 
alternatives. Don't describe the change -- we can read diffs. Describe the 
solution; describe the issue you found and how you're fixing it; describe your 
clever hacks; etc.

We generally use the imperative for commit messages ("Fix this" or "Make that 
, but third person present indicative ("Fixes this" and "Makes that") as well 
as past tense ("Fixed this" and "Made that") are fine. A commit message is 
always attached to a commit, so it's co-temporal with it.

The changelog, however, is not intended for other Qt developers. It's intended 
for Qt users, to be published on our website along with the release. Users 
don't care how a bug was fixed, only that it was; they don't care much about 
what the old and broken behaviour was, they care about what the new behaviour 
is. Changelogs are not attached to commits, but instead to releases and they 
refer to things that happened in the development of that release. That's why 
you describe things that happened in the past ("Fixed a bug") or about 
behaviour that the user should expect now and in the future.

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