From owner-freebsd-hackers@freebsd.org Wed Apr 13 00:24:48 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 79166B0DBF2 for ; Wed, 13 Apr 2016 00:24:48 +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 199E51D0E for ; Wed, 13 Apr 2016 00:24:47 +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; 13 Apr 2016 09:49:05 +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 u3D0Iw5U015861 (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Wed, 13 Apr 2016 09:49:03 +0930 (CST) (envelope-from darius@dons.net.au) From: "O'Connor, Daniel" Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable Date: Wed, 13 Apr 2016 09:48:57 +0930 Subject: Improving commit logs To: FreeBSD Hackers Message-Id: <56FF6534-276E-4E52-871F-5567BD9D6EC7@dons.net.au> Mime-Version: 1.0 (Mac OS X Mail 9.3 \(3124\)) 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: Wed, 13 Apr 2016 00:24:48 -0000 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