[Bf-committers] Commit logs

[Brecht Van Lommel]

Hi all,

In going over the commit logs for the release notes, I found many are quite
cryptic, or could be improved so that it's easier to make release notes
from them. I don't want to make strict guidelines for how things should be
formatted, just some general hints:

Bug fixes:
* Don't copy the bug report name verbatim if it's not descriptive, explain
what exactly the problem was.
* Explain what you fixed on a user level, not just what was wrong in the
code. Do explain those things too, but please do both then.
* Start the commit log with "Fix #12345: ", so it's immediately clear that
it's a bugfix.

Features:
* Explain what the feature does on a user level, not just the code changes.
* Keep user level explanation and code changes explanation separate.
* Explain features in terms of their names in the user interface, not
internal code terminology.
* If it's not obvious, explain what the feature is useful for or when it
should be used.

Code refactoring:
* Make it clear when there are no functional changes, I like to start the
commit with "Code cleanup: " then.

Thanks,
Brecht.