From owner-cvs-all Tue Nov 27 15: 9:58 2001 Delivered-To: cvs-all@freebsd.org Received: from mail.rpi.edu (mail.rpi.edu [128.113.22.40]) by hub.freebsd.org (Postfix) with ESMTP id A7C6F37B416; Tue, 27 Nov 2001 15:09:52 -0800 (PST) Received: from [128.113.24.47] (gilead.acs.rpi.edu [128.113.24.47]) by mail.rpi.edu (8.11.3/8.11.3) with ESMTP id fARN9pD18466; Tue, 27 Nov 2001 18:09:51 -0500 Mime-Version: 1.0 X-Sender: drosih@mail.rpi.edu Message-Id: In-Reply-To: References: Date: Tue, 27 Nov 2001 18:09:49 -0500 To: Robert Watson , Mike Barcroft From: Garance A Drosihn Subject: Re: Committer's guide policy on commit message contents Cc: cvs-committers@FreeBSD.org, cvs-all@FreeBSD.org Content-Type: text/plain; charset="us-ascii" ; format="flowed" Sender: owner-cvs-all@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.ORG At 4:37 PM -0500 11/27/01, Robert Watson wrote: >On Tue, 27 Nov 2001, Mike Barcroft wrote: > >> From the Committers Guide: "Do not waste space in the commit messages >> explaining what you did. That is what cvs diff is for. Instead, tell >> us why you did it." > >Ignoring, for a moment, any context -- I think this is actually not a good >policy. In the event that there are complex or large changes being made, >a brief summary of the changes, along with the rationale, is appropriate >in the commit message. At least, that's my feeling :-). Is this >something that would be worth changing? I think the "explaining what you did" means at the level of C code. Ie, a commit message should not say "I changed friprtn() to initialize 'lvl' to zero". That is explaining what you did. It does not explain why you did it. "I fixed the a problem where login will sometimes fail with the message 'index out of range'". That is why you made the change. That's how I have always read it, at least. Reading it again, perhaps it is confusing to say "explaining what you did". After all, if you do say *why* you made the change, then you are in some sense "explaining what you did". Perhaps that should say "listing the lines of code that you changed". -- Garance Alistair Drosehn = gad@eclipse.acs.rpi.edu Senior Systems Programmer or gad@freebsd.org Rensselaer Polytechnic Institute or drosih@rpi.edu To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe cvs-all" in the body of the message