Date: Wed, 13 Apr 2016 09:48:57 +0930 From: "O'Connor, Daniel" <darius@dons.net.au> To: FreeBSD Hackers <freebsd-hackers@freebsd.org> Subject: Improving commit logs Message-ID: <56FF6534-276E-4E52-871F-5567BD9D6EC7@dons.net.au>
next in thread | raw e-mail | index | archive | help
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-messa= ge.html) except for the mechanical (PR, Reviewed By, etc). I propose changing the top part of it to.. =3D=3D=3D=3D=3D SNIP =3D=3D=3D=3D=3D 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. =3D=3D=3D=3D=3D SNIP =3D=3D=3D=3D=3D 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?56FF6534-276E-4E52-871F-5567BD9D6EC7>