From owner-freebsd-hackers@freebsd.org Thu Apr 14 03:52:41 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 808F6B0F461 for ; Thu, 14 Apr 2016 03:52:41 +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 E43D91205; Thu, 14 Apr 2016 03:52:40 +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 13:22:38 +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 u3E3qWaA047783 (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Thu, 14 Apr 2016 13:22:37 +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=us-ascii From: "O'Connor, Daniel" In-Reply-To: <20160414034805.GR18163@FreeBSD.org> Date: Thu, 14 Apr 2016 13:22:31 +0930 Cc: Ngie Cooper , FreeBSD Hackers Content-Transfer-Encoding: quoted-printable Message-Id: <9FD838FE-E1DF-487D-82BF-77EEA2C51156@dons.net.au> References: <56FF6534-276E-4E52-871F-5567BD9D6EC7@dons.net.au> <20160414032801.GP18163@FreeBSD.org> <1DDB0BFB-545F-4293-9BFB-020DAFD7A5C4@dons.net.au> <20160414034320.GQ18163@FreeBSD.org> <2FD1641C-DF99-4464-BA34-A05430D663C4@dons.net.au> <20160414034805.GR18163@FreeBSD.org> To: Glen Barber 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 03:52:41 -0000 > On 14 Apr 2016, at 13:18, Glen Barber wrote: >=20 > On Thu, Apr 14, 2016 at 01:14:46PM +0930, O'Connor, Daniel wrote: >>=20 >>> On 14 Apr 2016, at 13:13, Glen Barber wrote: >>> I absolutely agree with you that a guide on this will be beneficial. >>> Sorry if my reply was taken any other way. >>>=20 >>> If I had a genie in a bottle, my three wishes would be: >>>=20 >>> 1) Better commit messages that address the "what"; >>> 2) Better explanation on the "why"; >>=20 >> Huh interesting, I definitely would pick 2 before 1 but I can see >> what you mean for a lot of commits (especially to 30 year old cruft >> filled esoterica) > When writing release notes, for example, the "what" is generally more > useful than the "why." In other words, the end user does not = generally > care *why* something changed, but they want to know *what* changed. That's a good point, my original version was written more in the mind of = someone who understands the code already but as you (and ngie) point out = there are other consumers of the code. =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, *what* was = changed and to a lesser degree *how*. 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 can be skipped if it is 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. The commit logs are used by more people that just = other developers - they are used to develop tests and release notes as = well. Generally speaking *how* is obvious due to the diff itself assuming you = have used enough comments, but clever tricks should probably be = explained (or commented in the code). 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 >>> 3) More wishes. >>=20 >> You wish for more genies, wishing for more wishes is usually >> verboten.. ;) >=20 > I also want a pony. :) D'awwww :) -- 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