[Development] Changelogs for 5.3.0
Thiago Macieira
thiago.macieira at intel.com
Wed Apr 23 09:14:04 CEST 2014
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
More information about the Development
mailing list