From mboxrd@z Thu Jan 1 00:00:00 1970 From: John Darrington Subject: Re: [PATCH 4/6] gnu: linux-libre-beagle-bone-black: Remove kernel variant. Date: Wed, 28 Sep 2016 08:16:25 +0200 Message-ID: <20160928061625.GA27249@jocasta.intra> References: <20160926103447.31830-1-david@craven.ch> <20160926103447.31830-4-david@craven.ch> <20160926132344.GA23258@jocasta.intra> <20160926164934.GA25011@jocasta.intra> <8760pgubgx.fsf@netris.org> Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="qMm9M+Fa2AknHoGS" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:59254) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bp8Af-00052i-1I for guix-devel@gnu.org; Wed, 28 Sep 2016 02:16:46 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bp8AZ-0003hl-VW for guix-devel@gnu.org; Wed, 28 Sep 2016 02:16:43 -0400 Received: from de.cellform.com ([88.217.224.109]:56934 helo=jocasta.intra) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bp8AZ-0003fL-NX for guix-devel@gnu.org; Wed, 28 Sep 2016 02:16:39 -0400 Content-Disposition: inline In-Reply-To: <8760pgubgx.fsf@netris.org> List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: "Guix-devel" To: Mark H Weaver Cc: guix-devel --qMm9M+Fa2AknHoGS Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Tue, Sep 27, 2016 at 08:14:38PM -0400, Mark H Weaver wrote: =20 Our conventions for commit logs, which follow the GNU Coding Standards for Change Logs (see section 6.8 of the GNU Coding Standards), is that explanations belong in the comments of the code itself, not in the commit log. If that had been done in the example you give above, you would have known why the line was needed in a small fraction of the ti= me that it must have taken you to perform all the steps above. That can work in simple instances - where the change is a one liner or at l= east where the change is confined to a few consecutive lines in one file. But n= ot all changes are that simple. Sometimes it is necessary to make a change wh= ich=20 involves lots of small changes in lots of different places in lots of diffe= rent files. In such cases it would be rediculous to append a comment to each l= ine changed. In fact I have seen such code from the 1980s where almost every 4= th line has a comment like:=20 mode++; /* JMD 09/2/1981: Increment the mode count otherwise the crud wan= gler overflows=20 in the case where grunger regurtitates */ The occasional such comment is ok, but when it's every third line it does n= othing for readability nor comprehensibility. =20 However, I agree that commits that _remove_ code should include the rationale in the commit log, if the reason is not obvious and if there= 's no sensible place to put the explanation in the code. =20 What do you think? Well I certainly agree that adding a reason for a change is a good idea. E= ven if we do also have text in the message which is superfluous. J' Note to self: Must write an improved version of gnulib's git-log-to-change= log script which will satisfy the die-harders. --=20 Avoid eavesdropping. Send strong encrypted email. PGP Public key ID: 1024D/2DE827B3=20 fingerprint =3D 8797 A26D 0854 2EAB 0285 A290 8A67 719C 2DE8 27B3 See http://sks-keyservers.net or any PGP keyserver for public key. --qMm9M+Fa2AknHoGS Content-Type: application/pgp-signature; name="signature.asc" Content-Description: Digital signature -----BEGIN PGP SIGNATURE----- Version: GnuPG v1 iEYEARECAAYFAlfrYDkACgkQimdxnC3oJ7PX3QCeLztlFW4GnZkl2iNGlByPimA2 kD8AniJbszvukvvjOIiSkZE2OCdKbfwO =XJ8l -----END PGP SIGNATURE----- --qMm9M+Fa2AknHoGS--