From owner-svn-src-head@FreeBSD.ORG Sat Aug 21 21:48:51 2010 Return-Path: Delivered-To: svn-src-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id ED74C1065696; Sat, 21 Aug 2010 21:48:51 +0000 (UTC) (envelope-from rpaulo@freebsd.org) Received: from karen.lavabit.com (karen.lavabit.com [72.249.41.33]) by mx1.freebsd.org (Postfix) with ESMTP id 750ED8FC12; Sat, 21 Aug 2010 21:48:51 +0000 (UTC) Received: from d.earth.lavabit.com (d.earth.lavabit.com [192.168.111.13]) by karen.lavabit.com (Postfix) with ESMTP id E264911B93D; Sat, 21 Aug 2010 16:48:50 -0500 (CDT) Received: from 10.0.10.3 (54.81.54.77.rev.vodafone.pt [77.54.81.54]) by lavabit.com with ESMTP id S0YDTUEBVC55; Sat, 21 Aug 2010 16:48:50 -0500 Mime-Version: 1.0 (Apple Message framework v1081) Content-Type: text/plain; charset=us-ascii From: Rui Paulo In-Reply-To: Date: Sat, 21 Aug 2010 22:48:46 +0100 Content-Transfer-Encoding: quoted-printable Message-Id: <26CBB559-FA72-4688-92E9-ED9CEA151B2C@FreeBSD.org> References: <201008191131.o7JBV4Yf002412@svn.freebsd.org> <4C6D18BE.2000905@fer.hr> <4C6D95A8.9070105@FreeBSD.org> <20100819213159.B48418@maildrop.int.zabbadoz.net> <4C6DDB74.3090102@FreeBSD.org> <7186318F-0921-41E5-9641-3D6B45E0623B@FreeBSD.org> <4C701901.8030505@FreeBSD.org> To: Doug Barton X-Mailer: Apple Mail (2.1081) Cc: svn-src-head@FreeBSD.org, Ana Kukec , svn-src-all@FreeBSD.org, "Bjoern A. Zeeb" , src-committers@FreeBSD.org Subject: Re: svn commit: r211501 - in head/sys: modules modules/send netinet netinet6 sys X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 21 Aug 2010 21:48:52 -0000 On 21 Aug 2010, at 22:15, Doug Barton wrote: > On Sat, 21 Aug 2010, Rui Paulo wrote: >=20 >> On 21 Aug 2010, at 19:20, Doug Barton wrote: >>=20 >>> On 08/21/2010 05:07, Rui Paulo wrote: >>>>> Meanwhile, the fact that in the past code has been committed >>>>> without man pages is the exact cause of the problem you're >>>>> describing. It is certainly not a justification for continuing to >>>>> do it wrong. >>>>=20 >>>> Reverting code just because it doesn't have a man page is = pointless. >>>> Everyone can write the damn man page, but not everyone can write >>>> code. You should really take this into consideration when proposing = a >>>> commit to be reverted. >>>=20 >>> So let's assume that having lots of code in the tree without a man = page is a problem. Further, let's assume that we don't want the problem = to get worse. How do you propose that we accomplish that? >>=20 >> By writing man pages...? >=20 > But that's the status quo (I.e., hope that people will/eventually = write man pages for stuff) and it hasn't worked so far. The situation = isn't actually going to be improved until we make a change. A simple = (and I think abundantly reasonable) change that we can make today is, = "Don't allow new work to be committed without a man page." >=20 > Meanwhile, there are a lot of benefits to this idea above and beyond = the obvious one of having man pages for stuff. The biggest single = benefit is that actually writing documentation for things forces you to = re-examine assumptions, work through non-obvious and/or non-default code = paths, etc. Speaking for myself, it's happened on more than one occasion = that as I sit down to document some piece of code I realize that there = are either bugs, or at least a better way of doing something. Requiring = developers to work through this process before code goes into the tree = gets us better code in addition to documentation. If your concern is to change the status quo, you do understand that you = picked the worst possible thread to hijack ? Esp. since the author = promised to roll out a man page. Regards, -- Rui Paulo