From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp.gentoo.org (smtp.gentoo.org [134.68.220.30]) by robin.gentoo.org (8.13.4/8.13.4) with ESMTP id j41LY0Qg011070 for ; Sun, 1 May 2005 21:34:00 GMT Received: from [62.254.189.226] (helo=snowdrop) by smtp.gentoo.org with esmtpa (Exim 4.43) id 1DSM4d-0000dv-BF for gentoo-dev@lists.gentoo.org; Sun, 01 May 2005 21:33:59 +0000 Received: from localhost ([127.0.0.1] helo=snowdrop) by snowdrop with esmtp (Exim 4.43) id 1DSM47-0006OI-L3 for gentoo-dev@lists.gentoo.org; Sun, 01 May 2005 22:33:27 +0100 Date: Sun, 1 May 2005 22:33:24 +0100 From: Ciaran McCreesh To: gentoo-dev@lists.gentoo.org Subject: [gentoo-dev] Unofficial Development Guide Message-ID: <20050501223324.7963f5c5@snowdrop> X-Mailer: Sylpheed-Claws 1.0.4 (GTK+ 1.2.10; i686-pc-linux-gnu) X-Message-Flag: It's a feature, not a bug 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: multipart/signed; boundary=Signature_Sun__1_May_2005_22_33_24_+0100_rAI3j2qa4tYe7CVf; protocol="application/pgp-signature"; micalg=pgp-sha1 X-Archives-Salt: 5d5eaef3-a886-430e-8a4e-3abeac473507 X-Archives-Hash: 1d723bca15a9b62597e718370e5d6fcc --Signature_Sun__1_May_2005_22_33_24_+0100_rAI3j2qa4tYe7CVf Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: quoted-printable ... also known in its former lives as the "Bash Guide" and "The Doc". Ok, I think I've held off announcing this for long enough now. It's not complete, and there's a lot of stuff I'd like to rewrite, but I've been persuaded to announce this anyway on the grounds that some people find it useful and would like to be able to refer to it, even in its unfinished state. Apparently I'm supposed to "release early, release often". What this is: An attempt to document existing Gentoo development practice. The focus is upon 'main tree' things, since that's what I know. The target audience is existing developers and potential recruits -- an existing knowledge of Gentoo from the user perspective is assumed. What this is not: This is not a list of hard rules like, say, the Debian Policy Manual. I personally don't think that that style of hard policy would work for Gentoo. There are exceptions to most rules -- I'm hoping that by explaining the reason behind these rules, rather than just stating "thou shalt not", the reader can get a better idea of when to break the rules and how to do so safely. This is not an official Gentoo thing. It may not mirror Gentoo Policy or the official party line. In some places this is intentional, in others it's a mistake. How it is presented: I'm aiming for a practical approach as far as possible. I've also tried to keep individual sections reasonably separate but with relevant references to other sections. I've tried to use realistic (even real where possible) examples. However, there aren't many nice simple ebuilds in the tree that don't have at least one weird part that would take a lot of irrelevant explanation, so sometimes I've used cut down or made up examples. What still needs doing: Lots. You *will* come across TODO sections, things that aren't well explained, things that need rewriting, things that aren't properly formatted and things that are incorrect. Most sections are about half as big as they need to be to cover everything properly. If you don't like that kind of thing, don't read this. How to contribute: For now, the best way to contribute is to send me text. If you know RST, diffs against the source (link in the page footers) are good. Otherwise, plain text is fine too. I do reserve the right to modify any submissions, but I will of course discuss them with you first if it's anything other than small formatting or wording changes. I might also tell you to go away, but that's fairly unlikely and hasn't happened so far. If you're working on a section or thinking about working on a section, it's probably a good idea to give me a prod first just in case anyone else had the same idea. Sections that already have tentative authors have been marked. Don't ask for the Makefile. Trust me, it's scary, unreliable and you don't want to see it. If I get it to the point where it'll parallel build and work with