Improving the build docs

[Jason Holt <credentiality gmail com>]

Hello gnome folks.  Lately I've been getting set up to contribute code to gedit; the "Get Involved" tab on gnome.org is very inviting!

But the actual process has been really painful.  That was surprising to me, since I went out of my way to do things in as mainstream a way as possible.

Can we make the docs clearer?  Here's my best guess at what prospective new developers need:

• Distinguish between people who want to contribute patches and people who just need to build the binaries -- I think that building from the source tarball of the version of the apps I use on my system would actually be pretty easy.  But maintainers want patches against the top of trunk, and that's a much more involved process.  As a prospective contributor, that difference wasn't obvious to me; I assumed it'd be easy to compile the latest sources.
• As far as I can tell, there are only two ways it's even possible to compile against the latest code: run an alpha distro, or use jhbuild.  The folks on IRC tell me that jhbuild is what everyone actually does, so we should find a way to point prospective developers at jhbuild early, before they start breaking their distros like I did.  (I even spent a day trying to figure out how to run an alpha distro in a VM)
• Give end-to-end examples of a complete build from top-of-trunk.  I can't quite figure out why I had so much trouble compiling with jhbuild on my fresh Lucid install.  I think the developers either A: all went through similar pain fixing undocumented things, or B: are using some other distro that works really easily with jhbuild.  In both cases, we should get the prerequisites documented right.  In particular, it's tough for newer users to figure out what package to install when a ./configure bombs.

Here's the path I've taken for the last week trying to get things to build:

gnome.org -> "Get Involved" -> "GNOME Love Initiative" -> gedit -> "ah!  it's in git"

search for "gnome git" -> live.gnome.org/Git -> http://live.gnome.org/Git/Developers

That process actually worked pretty well -- I was able to download the sources and we even submitted a simple patch to the "INSTALL" doc for gedit mentioning how to do it.  Actually building it, though, gave me errors about my libraries being too old.  

That sent me down the wrong path completely: I downloaded about 3 different distros of Ubuntu and Fedora 15 (per the recommendation on gnome.org), trying to find one with sufficiently recent libraries to compile.  The alpha release of Ubuntu Oneiric was actually new enough to get gedit to compile, but so unstable that it left my machine unbootable.

Finally a friend mentioned IRC.  (BTW, a web interface like http://webchat.freenode.net/ would have been really handy).  I asked there, and people pointed me toward jhbuild.  jhbuild didn't work on my old Ubuntu Hardy machine, so I installed a fresh copy of Lucid.

The jhbuild docs were pretty good, but I got funky errors about libraries being out of date, which sent me back to IRC, where we eventually narrowed it down to a bug in jhbuild, which I just filed.

Once I fixed that, it has been chugging away for a long time building a bunch of dependencies like NetworkManager, which don't seem like they should really be prerequisites for gedit, and occasionally failing when it needs me to install a new system library.