[gentoo-dev] Unofficial Development Guide

[Ciaran McCreesh]

... 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 <bash-3 and <vim-7, I'll post it somewhere.

Who to thank:

I'd like to thank g2boojum, ka0ttic, rac and slarti for big chunks of
content, and agriffis, seemant, azarah, superlag, dmwaters, swift,
weeve, jstubbs, ferringb and genone for miscellaneous help along the way
(even if some of them didn't realise what they were doing at the time).
Also thanks to the various people who have read over parts of it and
found some of the many typos and screwups. I've probably forgotten
several people -- sorry guys, I'm getting forgetful in my old age. Also
thanks to all those people whose ebuilds I nicked.

Who not to thank:

Uh, you all already know that.

Where it is:

Obviously, this isn't on Gentoo hardware. For now, it's at the link
below. I think the box it's on can cope with serving up static HTML
content and a few images (yes, we have images! four of them!), but if
not I'll blag some free webspace off someone (probably Berlios) and post
an updated URL.

    http://www.firedrop.org.uk/devmanual/

Sorry, there's no single page version yet. It's something that I could
do easily enough with the backend I'm using, but I'm more interested in
content for now.

Anyway, if you don't like it, feel free to ignore it. Or better yet,
post whiny Elmo bitchfest emails about it -- if they're good, I'll print
them out and hang them on my wall.


-- 
Ciaran McCreesh : Gentoo Developer (Vim, Fluxbox, shell tools)
Mail            : ciaranm at gentoo.org
Web             : http://dev.gentoo.org/~ciaranm