From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Giorgos Keramidas Newsgroups: gmane.emacs.devel Subject: Re: Summarizing the purpose of a change. Date: Sat, 21 Nov 2009 13:29:14 +0200 Message-ID: <874oooyv3p.fsf@kobe.laptop> References: <87iqd4tkv4.fsf@red-bean.com> <87bpiwz4fy.fsf@catnip.gol.com> <83iqd4p7ik.fsf@gnu.org> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: ger.gmane.org 1258802993 15639 80.91.229.12 (21 Nov 2009 11:29:53 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 21 Nov 2009 11:29:53 +0000 (UTC) Cc: kfogel@red-bean.com, emacs-devel@gnu.org, Miles Bader To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Nov 21 12:29:45 2009 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1NBo9w-0006WF-ET for ged-emacs-devel@m.gmane.org; Sat, 21 Nov 2009 12:29:45 +0100 Original-Received: from localhost ([127.0.0.1]:48461 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1NBo9v-0004eq-Ow for ged-emacs-devel@m.gmane.org; Sat, 21 Nov 2009 06:29:43 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1NBo9n-0004eR-UM for emacs-devel@gnu.org; Sat, 21 Nov 2009 06:29:35 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1NBo9j-0004dT-Oe for emacs-devel@gnu.org; Sat, 21 Nov 2009 06:29:35 -0500 Original-Received: from [199.232.76.173] (port=41184 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1NBo9j-0004dQ-GK for emacs-devel@gnu.org; Sat, 21 Nov 2009 06:29:31 -0500 Original-Received: from poseidon.ceid.upatras.gr ([150.140.141.169]:58462) by monty-python.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1NBo9Z-0004jE-SI; Sat, 21 Nov 2009 06:29:22 -0500 Original-Received: from mail.ceid.upatras.gr (unknown [10.1.0.143]) by poseidon.ceid.upatras.gr (Postfix) with ESMTP id AB077EB488E; Sat, 21 Nov 2009 13:29:18 +0200 (EET) Original-Received: from localhost (europa.ceid.upatras.gr [127.0.0.1]) by mail.ceid.upatras.gr (Postfix) with ESMTP id 9D7CE452A4; Sat, 21 Nov 2009 13:29:18 +0200 (EET) X-Virus-Scanned: amavisd-new at ceid.upatras.gr Original-Received: from mail.ceid.upatras.gr ([127.0.0.1]) by localhost (europa.ceid.upatras.gr [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 7Vx8ogDGSvlh; Sat, 21 Nov 2009 13:29:18 +0200 (EET) Original-Received: from kobe.laptop (ppp-94-64-242-88.home.otenet.gr [94.64.242.88]) by mail.ceid.upatras.gr (Postfix) with ESMTP id 384B7451B2; Sat, 21 Nov 2009 13:29:18 +0200 (EET) Original-Received: from kobe.laptop (kobe.laptop [127.0.0.1]) by kobe.laptop (8.14.3/8.14.3) with ESMTP id nALBTGsa048614 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Sat, 21 Nov 2009 13:29:16 +0200 (EET) (envelope-from keramida@kobe.laptop) Original-Received: (from keramida@localhost) by kobe.laptop (8.14.3/8.14.3/Submit) id nALBTFfO048611; Sat, 21 Nov 2009 13:29:15 +0200 (EET) (envelope-from keramida) In-Reply-To: <83iqd4p7ik.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 21 Nov 2009 11:11:15 +0200") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.1.50 (berkeley-unix) X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6 (newer, 3) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:117427 Archived-At: On Sat, 21 Nov 2009 11:11:15 +0200, Eli Zaretskii wrote: >Karl Fogel writes: >>> In many projects, there is a convention of summarizing the purpose of a >>> change in one or two sentences at the start of the log entry. This makes >>> the rest of the log entry (and the change itself) easier to understand. >> >> And if possible, make the summary not "1 or 2" sentences, but a single >> not-to-long line, such as you'd use for an email Subject: header. > > I suspect pointing to the relevant discussion on emacs-devel, or to a > bug number (if there is any) would be a lesser burden. Yes, when there *is* a bug number this is useful. A short summary in the first line of each commit is often useful for other changes too; changes that are not necessarily bug fixes. For example, Bazaar has a "--line" option that can display long lists of changesets by showing a single-line summary for each commit. In a small sample repository with the following history: : keramida@kobe:/tmp/koko$ bzr log : ------------------------------------------------------------ : revno: 3 : committer: Giorgos Keramidas : branch nick: koko : timestamp: Sat 2009-11-21 13:19:31 +0200 : message: : bug #27 -- add a '.localnet' suffix to the default 'foo' name : : The installation scripts can set the default domain name to a more : sensible value, but there are bits of the installer code that may : have to read 'foo' before DNS, NIS or some other resolver scheme : is up and running. So add a default '.localnet' domain part to : the name of 'foo', and let the resolver code replace it with the : real domain name later. : ------------------------------------------------------------ : revno: 2 : committer: Giorgos Keramidas : branch nick: koko : timestamp: Sat 2009-11-21 13:18:24 +0200 : message: : bug #19 -- 'foo' always displays a short name : : We need the full name of the 'foo' utility here. Shortening the name : to something less chatty can be done by the GUI utilities. : ------------------------------------------------------------ : revno: 1 : committer: Giorgos Keramidas : branch nick: koko : timestamp: Sat 2009-11-21 13:18:07 +0200 : message: : Add foo : keramida@kobe:/tmp/koko$ the bzr(1) utility can show a short summary of all the changes in just 3 lines of output: : keramida@kobe:/tmp/koko$ bzr log --line : 3: Giorgos Keramidas 2009-11-21 bug #27 -- add a '.localnet' suffix to the default 'foo' name : 2: Giorgos Keramidas 2009-11-21 bug #19 -- 'foo' always displays a short name : 1: Giorgos Keramidas 2009-11-21 Add foo : keramida@kobe:/tmp/koko$ The format of the commits logs I used in the sample repository make the short log summary more useful because their first line includes enough context about the intent of each change.