From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 14976 invoked by alias); 2 Dec 2007 11:43:00 -0000 Received: (qmail 14966 invoked by uid 22791); 2 Dec 2007 11:43:00 -0000 X-Spam-Check-By: sourceware.org Received: from anyanka.rfc1149.net (HELO mail2.rfc1149.net) (81.56.47.149) by sourceware.org (qpsmtpd/0.31) with ESMTP; Sun, 02 Dec 2007 11:42:56 +0000 Received: from localhost (localhost [127.0.0.1]) by mail2.rfc1149.net (Postfix) with ESMTP id E1D01C405C; Sun, 2 Dec 2007 12:42:51 +0100 (CET) Received: from mail2.rfc1149.net ([127.0.0.1]) by localhost (localhost [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id avjnyys6yozF; Sun, 2 Dec 2007 12:42:51 +0100 (CET) Received: by mail2.rfc1149.net (Postfix, from userid 1000) id ADBF0C405E; Sun, 2 Dec 2007 12:42:51 +0100 (CET) To: Andreas Schwab Cc: gcc@gcc.gnu.org Subject: Re: Rant about ChangeLog entries and commit messages References: <2007-12-02-11-05-39+trackit+sam@rfc1149.net> Date: Sun, 02 Dec 2007 11:43:00 -0000 In-Reply-To: (Andreas Schwab's message of "Sun\, 02 Dec 2007 11\:23\:30 +0100") User-Agent: Gnus/5.11 (Gnus v5.11) Emacs/22.1 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii From: Samuel Tardieu Content-Transfer-Encoding: 8bit X-WWW: http://www.rfc1149.net/sam X-Jabber: (see http://www.jabber.org/) X-OpenPGP-Fingerprint: 79C0 AE3C CEA8 F17B 0EF1 45A5 F133 2241 1B80 ADE6 (see http://www.gnupg.org/) Message-Id: <2007-12-02-12-42-51+trackit+sam@rfc1149.net> Mailing-List: contact gcc-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Archive: List-Post: List-Help: Sender: gcc-owner@gcc.gnu.org X-SW-Source: 2007-12/txt/msg00024.txt.bz2 Sam> How could a newcomer guess why the gcc_force_collect flag needs to Sam> be reset? Andreas> That is supposed to be written in a comment. The change log Andreas> entry should describe _what_ is being changed, so that you Andreas> can find out when a particular change was made. Out of curiosity, I looked for an example with one of your own commits in the Linux kernel tree and I found one: I think http://tinyurl.com/2j7lt7 is a very helpful explanation of the corresponding change (http://tinyurl.com/2tpw8l). Someone trying to fix a similar bug in another driver will benefit from having this message in the VCS history. A comment in the code would probably have been much shorter than this explanation and would probably not contain the "headphone", "line out" and "muted" words. Once again, I agree that the current mechanism works for GCC developers, but I think it could be much better if: 1- commit messages didn't duplicate ChangeLog entries (maybe by getting rid of ChangeLogs) 2- commit messages contained a synthetic information such as the one provided for peer-review I'm not trying to launch a revolution in the GCC development process, I'm only comparing two ways of documenting changes as they are committed and explaining why I find the Linux way of doing it more useful. As a side note, I know several (sick?) people (including myself) who casually read the Linux kernel RSS feed in their RSS aggregator and find it very insightful (if you exclude the "Merge" messages) while lighter than reading the whole linux-kernel mailing-list. People reading this can look at http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=atom with RSS-capable software to see what I mean. The GCC ChangeLogs, even when aggregated, aren't as nice to read when you're having breakfast :) Sam