From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: ludo@gnu.org (Ludovic =?iso-8859-1?Q?Court=E8s?=) Newsgroups: gmane.lisp.guile.devel Subject: ChangeLog or not? Date: Tue, 06 Mar 2012 18:33:42 +0100 Message-ID: <87ipih8wi1.fsf@gnu.org> References: NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: dough.gmane.org 1331055272 8983 80.91.229.3 (6 Mar 2012 17:34:32 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Tue, 6 Mar 2012 17:34:32 +0000 (UTC) To: guile-devel@gnu.org Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Tue Mar 06 18:34:30 2012 Return-path: Envelope-to: guile-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1S4yHH-0005lS-2w for guile-devel@m.gmane.org; Tue, 06 Mar 2012 18:34:23 +0100 Original-Received: from localhost ([::1]:57873 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1S4yHG-0003Hq-Cx for guile-devel@m.gmane.org; Tue, 06 Mar 2012 12:34:22 -0500 Original-Received: from eggs.gnu.org ([208.118.235.92]:39623) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1S4yH4-0002ny-Lm for guile-devel@gnu.org; Tue, 06 Mar 2012 12:34:16 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1S4yGe-0005HC-W4 for guile-devel@gnu.org; Tue, 06 Mar 2012 12:34:10 -0500 Original-Received: from xanadu.aquilenet.fr ([88.191.123.111]:35641) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1S4yGe-0005Fo-Q4 for guile-devel@gnu.org; Tue, 06 Mar 2012 12:33:44 -0500 Original-Received: from localhost (xanadu.aquilenet.fr [127.0.0.1]) by xanadu.aquilenet.fr (Postfix) with ESMTP id 214587240 for ; Tue, 6 Mar 2012 18:33:43 +0100 (CET) Original-Received: from xanadu.aquilenet.fr ([127.0.0.1]) by localhost (xanadu.aquilenet.fr [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id zhNAaw2LtmKR for ; Tue, 6 Mar 2012 18:33:43 +0100 (CET) Original-Received: from pluto (unknown [193.50.110.167]) by xanadu.aquilenet.fr (Postfix) with ESMTPSA id DA34A720B for ; Tue, 6 Mar 2012 18:33:42 +0100 (CET) X-URL: http://www.fdn.fr/~lcourtes/ X-Revolutionary-Date: 17 =?iso-8859-1?Q?Vent=F4se?= an 220 de la =?iso-8859-1?Q?R=E9volution?= X-PGP-Key-ID: 0xEA52ECF4 X-PGP-Key: http://www.fdn.fr/~lcourtes/ludovic.asc X-PGP-Fingerprint: 83C4 F8E5 10A3 3B4C 5BEA D15D 77DD 95E2 EA52 ECF4 X-OS: x86_64-unknown-linux-gnu In-Reply-To: (Mark H. Weaver's message of "Sat, 03 Mar 2012 23:09:28 +0000") User-Agent: Gnus/5.110018 (No Gnus v0.18) Emacs/24.0.93 (gnu/linux) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-Received-From: 88.191.123.111 X-BeenThere: guile-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Developers list for Guile, the GNU extensibility library" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Original-Sender: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.lisp.guile.devel:14027 Archived-At: Hello! I sympathize with the idea of ChangeLogs as in the GCS (info "(standards) Change Log Concepts"), and in particular: There's no need to describe the full purpose of the changes or how they work together. However, sometimes it is useful to write one line to describe the overall purpose of a change or a batch of changes. If you think that a change calls for explanation, you're probably right. Please do explain it--but please put the full explanation in comments in the code, where people will see it whenever they see the code. For example, "New function" is enough for the change log when you add a function, because there should be a comment before the function definition to explain what it does. I think it makes it easier to review patches, and to understand the code. Alas, that convention is not widely followed in Guile. I really think it makes a lot of sense though, and would love to see us use it more. WDYT? Are you more comfortable with the opposite approach? Do you think it=E2=80=99s bikeshedding? :-) Thanks, Ludo=E2=80=99.