Merge lp:~jml/launchpad/readme into lp:launchpad

[Jonathan Lange]

Write a real README.

I thought, you know what would be a good idea? A README file! It should explain what Launchpad is, where one could go to find more information and give some tips on how to navigate the code base.

As for style, I aimed to be clear, direct and interesting to read without being cute. I also aimed to be honest about our flaws without being better. How well I hit the mark is up to you.

[Francis J. Lacoste (flacoste)]

That's great!

I think you hit the mark. Couldn't spot even a typo!

review: Approve

[Robert Collins (lifeless)]

Hey Francis, please hit the 'Merge' scope 'Approve' button as well - it takes it out of the 'to-review' queue :).

=== modified file 'README'
--- README	2010-04-06 20:07:30 +0000
+++ README	2010-08-10 18:28:49 +0000
@@ -1,4 +1,106 @@
-This is the top level project, that supplies the infrastructure for testing,
-and running launchpad.
-
-Documentation is in the doc directory or on the wiki.
+====================
+README for Launchpad
+====================
+
+Launchpad is an open source suite of tools that help people and teams to work
+together on software projects.  Unlike many open source projects, Launchpad
+isn't something you install and run yourself (although you are welcome to do
+so), instead, contributors help make <https://launchpad.net> better.
+
+Launchpad is a project of Canonical <http://www.canonical.com> and has
+received many contributions from many wonderful people
+<https://dev.launchpad.net/Contributions>.
+
+If you want help using Launchpad, then please visit our help wiki at:
+
+    https://help.launchpad.net
+
+If you'd like to contribute to Launchpad, have a look at:
+
+    https://dev.launchpad.net
+
+Alternatively, have a poke around in the code, which you probably already know
+how to get if you are reading this file.
+
+
+Getting started
+===============
+
+There's a full guide for getting up-and-running with a development Launchpad
+environment at <https://dev.launchpad.net/Getting>.  When you are ready to
+submit a patch, please consult <https://dev.launchpad.net/PatchSubmission>.
+
+Our bug tracker is at <https://bugs.launchpad.net/launchpad/> and you can get
+the source code any time by doing:
+
+  $ bzr branch lp:launchpad
+
+
+Navigating the tree
+-------------------
+
+The Launchpad tree is big, messy and changing.  Sorry about that.  Don't panic
+though, it can sense fear.  Keep a firm grip on `grep` and pay attention to
+these important top-level folders:
+
+  bin/, utilities/
+    Where you will find scripts intended for developers and admins.  There's
+    no rhyme or reason to what goes in bin/ and what goes in utilities/, so
+    take a look in both. bin/ will be empty in a fresh checkout, the actual
+    content lives in 'buildout-templates'.
+
+  configs/
+    Configuration files for various kinds of Launchpad instances.
+    'development' and 'testrunner' are of particular interest to developers.
+
+  cronscripts/
+    Scripts that are run on actual production instances of Launchpad as
+    cronjobs.
+
+  daemons/
+    Entry points for various daemons that form part of Launchpad
+
+  database/
+    Our database schema, our sample data, and some other stuff that causes
+    fear.
+
+  doc/
+    General system-wide documentation. You can also find documentation on
+    <https://dev.launchpad.net>, in docstrings and in doctests.
+
+  lib/
+    Where the vast majority of the code lives, along with our templates, tests
+    and the bits of our documentation that are written as doctests. 'lp' and
+    'canonical' are the two most interesting packages. Note that 'canonical'
+    is deprecated in favour of 'lp'.  To learn more about how the 'lp' package
+    is laid out, take a look at its docstring.
+
+  Makefile
+    Ahh, bliss.  The Makefile has all sorts of goodies.  If you spend any
+    length of time hacking on Launchpad, you'll use it often.  The most
+    important targets are 'make clean', 'make compile', 'make schema', 'make
+    run' and 'make run_all'.
+
+  scripts/
+    Scripts that are run on actual production instances of Launchpad,
+    generally triggered by some automatic process.
+
+
+You can spend years hacking on Launchpad full-time and not know what all of
+the files in the top-level directory are for.  However, here's a guide to some
+of the ones that come up from time to time.
+
+  buildout-templates/
+    Templates that are generated into actual files, normally bin/ scripts,
+    when buildout is run. If you want to change the behaviour of bin/test,
+    look here.
+
+  bzrplugins/, optionalbzrplugins/
+    Bazaar plugins used in running Launchpad.
+
+  sourcecode/
+    A directory into which we symlink branches of some of Launchpad's
+    dependencies.  Don't ask.
+
+You never have to care about 'benchmarks', 'override-includes' or
+'package-includes'.