From owner-freebsd-hackers@freebsd.org Thu Apr 14 02:48:37 2016 Return-Path: Delivered-To: freebsd-hackers@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id E0F58B0F300 for ; Thu, 14 Apr 2016 02:48:37 +0000 (UTC) (envelope-from darius@dons.net.au) Received: from ipmail04.adl6.internode.on.net (ipmail04.adl6.internode.on.net [150.101.137.141]) by mx1.freebsd.org (Postfix) with ESMTP id 5628514AB; Thu, 14 Apr 2016 02:48:36 +0000 (UTC) (envelope-from darius@dons.net.au) Received: from ppp14-2-34-252.lns21.adl2.internode.on.net (HELO midget.dons.net.au) ([14.2.34.252]) by ipmail04.adl6.internode.on.net with ESMTP; 14 Apr 2016 12:18:03 +0930 Received: from [10.0.2.26] ([10.0.2.26]) (authenticated bits=0) by midget.dons.net.au (8.15.1/8.14.9) with ESMTPSA id u3E2lsRh003504 (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Thu, 14 Apr 2016 12:18:00 +0930 (CST) (envelope-from darius@dons.net.au) Subject: Re: Improving commit logs Mime-Version: 1.0 (Mac OS X Mail 9.3 \(3124\)) Content-Type: text/plain; charset=windows-1252 From: "O'Connor, Daniel" In-Reply-To: <570E7A46.4040401@FreeBSD.org> Date: Thu, 14 Apr 2016 12:17:54 +0930 Cc: FreeBSD Hackers Content-Transfer-Encoding: quoted-printable Message-Id: References: <56FF6534-276E-4E52-871F-5567BD9D6EC7@dons.net.au> <570E7A46.4040401@FreeBSD.org> To: Eric van Gyzen X-Mailer: Apple Mail (2.3124) X-Spam-Score: -2.9 () ALL_TRUSTED,BAYES_00 X-Scanned-By: MIMEDefang 2.75 on 10.0.2.1 X-BeenThere: freebsd-hackers@freebsd.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: Technical Discussions relating to FreeBSD List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 14 Apr 2016 02:48:38 -0000 > On 14 Apr 2016, at 02:26, Eric van Gyzen wrote: > On 04/12/16 07:18 PM, O'Connor, Daniel wrote: >> 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. Great :) >> 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. >=20 > 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. I agree, but this suggestion is only for the commit logs - I'm picking = my battles :) >> 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. >=20 > 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. I know, but I don't really think there is a set of rules which will = describe it without annoying 80% of the people using it (and different = rules will affect a different 80%...) >> 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. >=20 > 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. OK, I updated it below. > 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. Good idea. >> 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 >>=20 >> Does anyone have any (constructive) comments or feedback? >=20 > Thanks for your time and effort on this. Thanks for the feedback :) =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. You should try and = step into the mind set of someone who is familiar with FreeBSD but not = focussed on the particular area you have committed to. What is obvious = now can be obtuse in a few months when you or someone else is reviewing = the code to track down issues. 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 do not think this means you = only need a 1 line summary. Write the full log first, then summarise it = if possible. If you aren't sure, err on the side of a longer rather than = shorter commit message. 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 -- 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