From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: =?utf-8?Q?=C3=93scar_Fuentes?= Newsgroups: gmane.emacs.devel Subject: Commit netiquette. Date: Thu, 18 Feb 2010 00:44:23 +0100 Message-ID: <87eikjzaug.fsf@telefonica.net> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: ger.gmane.org 1266450299 32228 80.91.229.12 (17 Feb 2010 23:44:59 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Wed, 17 Feb 2010 23:44:59 +0000 (UTC) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Feb 18 00:44:56 2010 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.69) (envelope-from ) id 1NhtZf-0000jz-Gr for ged-emacs-devel@m.gmane.org; Thu, 18 Feb 2010 00:44:56 +0100 Original-Received: from localhost ([127.0.0.1]:45064 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1NhtZe-0007dz-2P for ged-emacs-devel@m.gmane.org; Wed, 17 Feb 2010 18:44:54 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1NhtZZ-0007dl-92 for emacs-devel@gnu.org; Wed, 17 Feb 2010 18:44:49 -0500 Original-Received: from [140.186.70.92] (port=33143 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1NhtZX-0007dB-Rd for emacs-devel@gnu.org; Wed, 17 Feb 2010 18:44:48 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1NhtZW-0006Jy-TF for emacs-devel@gnu.org; Wed, 17 Feb 2010 18:44:47 -0500 Original-Received: from lo.gmane.org ([80.91.229.12]:53085) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1NhtZW-0006Jo-FZ for emacs-devel@gnu.org; Wed, 17 Feb 2010 18:44:46 -0500 Original-Received: from list by lo.gmane.org with local (Exim 4.69) (envelope-from ) id 1NhtZO-0000Zb-W9 for emacs-devel@gnu.org; Thu, 18 Feb 2010 00:44:39 +0100 Original-Received: from 206.red-81-33-105.dynamicip.rima-tde.net ([81.33.105.206]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Thu, 18 Feb 2010 00:44:38 +0100 Original-Received: from ofv by 206.red-81-33-105.dynamicip.rima-tde.net with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Thu, 18 Feb 2010 00:44:38 +0100 X-Injected-Via-Gmane: http://gmane.org/ Original-Lines: 51 Original-X-Complaints-To: usenet@ger.gmane.org X-Gmane-NNTP-Posting-Host: 206.red-81-33-105.dynamicip.rima-tde.net User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.1.92 (gnu/linux) Cancel-Lock: sha1:mGazzCF+SaIancBj8n+Kfu4G5wg= X-detected-operating-system: by eggs.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:121172 Archived-At: It would be a Good Thing (TM) to explicitly set good practices for commits. People is accustomed to CVS and following those customs with changeset-based systems like Bazaar is counterproductive. VC history, like code, is written once but read a thousand times, so it is worth to write it with some care. A correct VC history can be exploited by tools that traverses it doing useful things (i.e. `bisect'). Let's look at one example: revno: 99513 committer: Mark A. Hershberger branch nick: local timestamp: Wed 2010-02-17 16:39:21 -0500 message: 2010-02-17 Mark A. Hershberger * vc-bzr.el: fix typo in Known Bugs section. * isearch.el (isearch-update-post-hook): New hook (isearch-update): Use the new hook. modified: lisp/ChangeLog lisp/isearch.el lisp/vc-bzr.el The Committer used the full Changelog entry as the commit message, so on interfaces that just shows the first line of the commit (like the emacs-diffs mailing list or the output of `bzr log --short' or `qlog') you see 2010-02-17 Mark A. Hershberger which is hardly indicative of the change. Ideally, the commit message should be made of a first line indicating the *purpose* of the change plus a longer text with a more complete explanation. Usually the changelog entry is good enough as the complete explanation (without the changelog's entry header!). If the changelog entry contains only one line and it is descriptive of the purpose of the change, it can be used as the commit message. In this case, it is preferable to remove the leading asterisk because it just adds noise and some text-based tools use asterisks for denoting nodes on the DAG. Another very important thing is to realize that a changeset-based VCS presents a view of the progress as a series of atomic steps that changes the content of the project. This is good because it allows to unambiguously establish the state of the project at certain point and identify the steps that caused that state. For this to be really useful, it is very important to not divide a change among several commits (i.e. by doing a commit for each edited file) and to not mix different changes on the same commit, as the case above.