Date: Wed, 13 Apr 2016 11:56:38 -0500 From: Eric van Gyzen <vangyzen@FreeBSD.org> To: "O'Connor, Daniel" <darius@dons.net.au>, FreeBSD Hackers <freebsd-hackers@freebsd.org> Subject: Re: Improving commit logs Message-ID: <570E7A46.4040401@FreeBSD.org> In-Reply-To: <56FF6534-276E-4E52-871F-5567BD9D6EC7@dons.net.au> References: <56FF6534-276E-4E52-871F-5567BD9D6EC7@dons.net.au>
next in thread | previous in thread | raw e-mail | index | archive | help
On 04/12/16 07:18 PM, O'Connor, Daniel wrote: > 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. I agree emphatically and appreciate your effort. > 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 same can be said about comments in the code. You might encourage people to answer "why" in comments wherever they think it might be helpful. > 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. When deciding what is "obvious", keep this in mind: When you have been neck-deep in this code for several days or weeks, think back to your level of understanding when you started working on these changes, and make your decision based on that understanding, since that is closer to the level of your audience. > 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. This wording encourages the whole commit log to be one line as often as possible. A one-line summary is a very good thing and is probably enough for most small, simple changes. However, for changes that are even moderately large or complex, I consider the one-liner a summary of the rest of the commit log, not of the whole code change. I would prefer to encourage longer commit logs, even to the point of making them too long. I would rather sift through paragraphs of stream-of-consciousness than try to reverse engineer the author's mind from a single phrase. It is said that perfection is the enemy of the sufficient. Although this is usually said about code, it applies here, too. Perhaps you could encourage people to write as much as they think is relevant, regardless of their English skills or other impediments. > 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 for your time and effort on this. Eric
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?570E7A46.4040401>