[docs] Make README more useful, add contributing doc

Change-Id: I1793246f2454ad48a93aa873a9f05b8593e85ae6

Author: swetland

README.md

@@ -1,8 +1,33 @@
-# MAGENTA REPOSITORY
+# Magenta
 
-Welcome to the Magenta repository.
+Magenta is the core platform that powers the Fuchsia OS.  Magenta is
+composed of a microkernel (source in kernel/...) as well as a small
+set of userspace services, drivers, and libraries (source in system/...)
+necessary for the system to boot, talk to hardware, load userspace
+processes and run them, etc.  Fuchsia builds a much larger OS on top
+of this foundation.
 
-The documentation is divided into
+The Magenta Kernel provides syscalls to manage processes, threads,
+virtual memory, inter-process communication, waiting on object state
+changes, and locking (via futexes).
 
-+ [Magenta](docs/index.md) specific.
-+ [LK](docs/lk/index.md) specific.
+Currently there are some temporary syscalls that have been used for early
+bringup work, which will be going away in the future as the long term
+syscall API/ABI surface is finalized.  The expectation is that there will
+be 10s, not 100s of syscalls.
+
+Magenta syscalls are generally non-blocking.  The wait (one, many, set)
+family of syscalls, ioport reads, and thread sleep being the notable
+exceptions.
+
+This page is a non-comprehensive index of the magenta documentation.
+
++ [Getting Started](docs/getting_started.md)
++ [Contributing Patches](docs/contributing.md)
++ [Relationship with LK](docs/mg_and_lk.md)
++ [Kernel Objects](docs/kernel_objects.md)
++ [Process Objects](docs/objects/process.md)
++ [Thread Objects](docs/objects/thread.md)
++ [Handles](docs/handles.md)
++ [Futexes](docs/futex.md)
++ [System Calls](docs/syscalls.md)

docs/contributing.md

@@ -0,0 +1,36 @@
+# Contributing Patches to Magenta
+
+At this point in time, Magenta is under heavy, active development, and we're
+not seeking major changes or new features from new contributors, but small
+bugfixes are welcome.
+
+Here are some general guidelines for patches to Magenta.  This list is
+incomplete and will be expanded over time:
+
+* GitHub pull requests are not accepted.  Patches are handled via
+  Gerrit Code Review at: https://fuchsia-review.googlesource.com/#/q/project:magenta
+
+* Indentation is with spaces, four spaces per indent.  Never tabs.
+Do not leave trailing whitespace on lines.  Gerrit will flag bad
+whitespace usage with a red background in diffs.
+
+* Match the style of surrounding code.
+
+* Avoid whitespace or style changes.  Especially do not mix style changes
+with patches that do other things as the style changes are a distraction.
+
+* Avoid changes that touch multiple modules at once if possible.  Most
+changes should be to a single library, driver, app, etc.
+
+* Include [tags] in the commit subject flagging which module, library,
+app, etc, is affected by the change.  The style here is somewhat informal.
+Look at past changes to get a feel for how these are used.
+
+* Magenta should be buildable for all major targets (x86-64, arm64, arm32)
+at every change.  ./scripts/build-all-magenta can help with this.
+
+* Avoid breaking the unit tests.  Boot Magenta and run "runtests" to
+verify that they're all passing.
+
+* The #fuchsia channel on the freenode irc network is a good place to ask
+questions.