From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from lists.gentoo.org ([140.105.134.102] helo=robin.gentoo.org) by finch.gentoo.org with esmtp (Exim 4.60) (envelope-from ) id 1Iy3IN-00030A-K4 for garchives@archives.gentoo.org; Fri, 30 Nov 2007 10:40:32 +0000 Received: from robin.gentoo.org (localhost [127.0.0.1]) by robin.gentoo.org (8.14.2/8.14.0) with SMTP id lAUAdcAD028090; Fri, 30 Nov 2007 10:39:38 GMT Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183]) by robin.gentoo.org (8.14.2/8.14.0) with ESMTP id lAUAbaP1025468 for ; Fri, 30 Nov 2007 10:37:36 GMT Received: from localhost (localhost [127.0.0.1]) by smtp.gentoo.org (Postfix) with ESMTP id A620265367 for ; Fri, 30 Nov 2007 10:37:35 +0000 (UTC) X-Virus-Scanned: amavisd-new at gentoo.org X-Spam-Score: -0.042 X-Spam-Level: X-Spam-Status: No, score=-0.042 required=5.5 tests=[AWL=0.490, BAYES_00=-2.599, RCVD_NUMERIC_HELO=2.067] Received: from smtp.gentoo.org ([127.0.0.1]) by localhost (smtp.gentoo.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id ceh1RfdALUVy for ; Fri, 30 Nov 2007 10:37:24 +0000 (UTC) Received: from ciao.gmane.org (main.gmane.org [80.91.229.2]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by smtp.gentoo.org (Postfix) with ESMTP id 1AA0A65363 for ; Fri, 30 Nov 2007 10:37:23 +0000 (UTC) Received: from list by ciao.gmane.org with local (Exim 4.43) id 1Iy3F6-0005Zc-AZ for gentoo-dev@gentoo.org; Fri, 30 Nov 2007 10:37:08 +0000 Received: from 91.84.77.94 ([91.84.77.94]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Fri, 30 Nov 2007 10:37:08 +0000 Received: from slong by 91.84.77.94 with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Fri, 30 Nov 2007 10:37:08 +0000 X-Injected-Via-Gmane: http://gmane.org/ To: gentoo-dev@lists.gentoo.org From: Steve Long Subject: [gentoo-dev] Re: [RFC] Features and documentation Date: Fri, 30 Nov 2007 10:42:03 +0000 Message-ID: References: <20071127192144.GP4368@supernova> <474D53CA.7060101@gentoo.org> Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-dev@gentoo.org Reply-to: gentoo-dev@lists.gentoo.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7Bit X-Complaints-To: usenet@ger.gmane.org X-Gmane-NNTP-Posting-Host: 91.84.77.94 User-Agent: KNode/0.10.4 Sender: news X-Archives-Salt: 5babec51-1375-4245-8fff-f1fccfbebb16 X-Archives-Hash: af14fb08e7c85826580df35729c4f46d Duncan wrote: > "Marijn Schouten (hkBst)" posted > 474D53CA.7060101@gentoo.org, excerpted below, on Wed, 28 Nov 2007 > 12:40:58 +0100: > >> Donnie Berkholz wrote: >>> How the recent changes happened to allow USE flag descriptions in >>> metadata.xml (which I'm not taking any position on now) gave me an >>> idea. The Linux kernel requires that any needed documentation accompany >>> all changes requiring said documentation -- part of the source-code >>> patch must apply to the Documentation/ directory. Should we require >>> that before you commit any changes, you (or someone) write the >>> documentation for them and commit it or submit a patch at the same >>> time? >> >> We're not talking about ebuilds here, are we? So what ARE we talking >> about? > > Agreed with hkBst and Ciaranm on this one. > It's kinda hard to discuss such a proposal without knowing where it is > going to be applied, or to read such discussion without being sure > everybody has the same target in mind (maybe it was discussed on IRC and > since I don't normally do that I missed it... seems I'm not the only one, > tho), and what it may be. > I took it to mean anything which changes something already documented on a gentoo doc website (including the devmanual but not individual dev space) or in a man page. That isn't so hard to define, while covering all the changes users or devs need to know about. One would hope devs would be aware of the docs relevant to the software they're changing, so I don't see that as onerous. Additions would count too; I'd imagine someone adding a new feature would want others to know about it. In that regard, asking them to talk to the doc team before it gets committed makes sense; often that process helps development. In the case of core software, or larger projects it might make sense for a point of contact in the doc team (although portage manpages seem to be updated pretty frequently.) While not privy to the prior (if any) discussion, I saw it as an attempt to make the development team aware of documentation responsibility, and asking them to bear that in mind when they change or add stuff (which we want them to do as that's how stuff improves) helps them to become more useful devs, imo. It doesn't have to mean sanctions at any point, but rather that someone would be put in touch with docs if they needed help to document stuff. I'd think new people would welcome that. -- gentoo-dev@gentoo.org mailing list