Improving commit logs
O'Connor, Daniel
darius at dons.net.au
Wed Apr 13 00:24:48 UTC 2016
Hi everyone,
Some people on IRC were commenting about how commit logs without a 'why' in them are much less useful (both to others and yourself in the future) and how this can be improved in the FreeBSD project.
Ed Maste pointed out that there is no real guidance about content of the commit log in the docs (https://www.freebsd.org/doc/en/articles/committers-guide/commit-log-message.html) except for the mechanical (PR, Reviewed By, etc).
I propose changing the top part of it to..
===== SNIP =====
This section contains some suggestions and traditions for how commit logs are formatted and what they should contain.
A commit log should explain *why* a commit has taken place, and to a lesser degree *how* and *what* was changed.
The why of a commit message is absolutely critical to allow other people (including your future self) to understand
the reason a change was made.
The how and what can be skipped if they are obvious (it's left as an exercise to the reader to determine what obvious is).
Generally speaking *what* is obvious due to the diff itself, the *how* can provide context and is more likely to be useful.
Due to the use of git and use of svn blame it is highly desirable to have a 1 line summary of the commit, however don't let that constrain you, a summary plus more detailed explanation is fine if necessary.
As well as including an informative message with each commit you may need to include some additional information.
===== SNIP =====
Does anyone have any (constructive) comments or feedback?
Thanks.
--
Daniel O'Connor
"The nice thing about standards is that there
are so many of them to choose from."
-- Andrew Tanenbaum
GPG Fingerprint - 5596 B766 97C0 0E94 4347 295E E593 DC20 7B3F CE8C
More information about the freebsd-hackers
mailing list