Update getting started instructions

* Move source control documentation to docs repository
* Add instructions for referencing issues in commit messages
* Split out monolithic jiri doc into smaller docs

Change-Id: I171e933aaac70b758ea9f290fb4339a5f0532a4a

CONTRIBUTING.md

-This repository accepts contributions using Gerrit.
+Contributing Changes
+====================
 
-Instructions for using Gerrit:
+Fuchsia manages commits through Gerrit at
+https://fuchsia-review.googlesource.com. Not all projects accept patches;
+please see the CONTRIBUTING.md document in individual projects for
+details.
 
- * https://gerrit-review.googlesource.com/Documentation/
+## Submitting changes
 
-Before we can land your change, you need to sign the Google CLA:
+To submit a patch to Fuchsia, you may first need to generate a cookie to
+authenticate you to Gerrit.  To generate a cookie, log into Gerrit and click
+the "Generate Password" link at the top of https://fuchsia.googlesource.com.
+Then, copy the generated text and execute it in a terminal.
+
+Once authenticated, follow these steps to submit a patch to Fuchsia:
+
+```
+# create a new branch
+git checkout -b branch_name
+
+# write some awesome stuff, commit to branch_name
+vim some_file ...
+git commit ...
+
+# upload the patch to gerrit
+git push origin HEAD:refs/for/master
+
+# once the change is landed, clean up the branch
+git branch -d branch_name
+```
+
+See the Gerrit documentation for more detail:
+[https://gerrit-documentation.storage.googleapis.com/Documentation/2.12.3/intro-user.html#upload-change](https://gerrit-documentation.storage.googleapis.com/Documentation/2.12.3/intro-user.html#upload-change)
+
+## [Googlers only] Issue actions
+
+Commit messages may reference issue IDs in Fuchsia's
+(issue tracker)[https://fuchsia.atlassian.net/]; such references will become
+links in the Gerrit UI. Issue actions may also be specified, for example to
+automatically close an issue when a commit is landed:
+
+BUG-123 #done
+
+`done` is the most common issue action, though any workflow action can be
+indicated in this way.
+
+*Note*: Fuchsia's issue tracker is not open to external contributors at this
+time.
+
+## Cross-repo changes
+
+Changes in two separate repos will be automatically tracked for you by Gerrit
+if you use the same topic.
+
+```
+# make and commit the first change, upload it with topic 'add_feature_foo'
+cd fuchsia/bin/fortune
+git checkout -b new add_feature_foo
+vim foo_related_files ...
+git commit ...
+git push origin HEAD:refs/for/master%topic=add_feature_foo
+
+# make and commit the second change in another repository
+cd fuchsia/build
+git checkout -b new add_feature_foo
+vim more_foo_related_files ...
+git commit ...
+git push origin HEAD:refs/for/master%topic=add_feature_foo
+
+# after the changes are reviewed, approved and submitted, cleanup the local branch
+cd fuchsia/bin/fortune
+git branch -d add_feature_foo
+
+cd fuchsia/build
+git branch -d add_feature_foo
+```
+
+Multipart changes are tracked in gerrit via topics, will be tested together,
+and can be landed in Gerrit at the same time with `Submit Whole Topic`. Topics
+can be edited via the web UI.
 
- * https://cla.developers.google.com/

building_toolchain.md

+# Building the toolchain
+
+To build Fuchsia's toolchain, you can use the `scripts/build-toolchain.sh`
+script as follows:
+
+```
+./scripts/build-toolchain.sh
+```
+
+After the build finishes, you can find the built toolchain in `out/toolchain`.
+
+Please note that build can take significant amount of time, especially on
+slower machines.
+
+When the sources get updated, you can rebuild the toolchain using the following
+commands:
+
+```sh
+# update
+jiri update
+
+# cleanup the artifacts from the previous build and rebuild the toolchain
+./scripts/build-toolchain.sh -c
+```

getting_source.md

+Fuchsia Source
+==============
+
+Fuchsia uses the `jiri` tool to manage git repositories
+[https://fuchsia.googlesource.com/jiri](https://fuchsia.googlesource.com/jiri).
+This tool manages a set of repositories specified by a manifest.
+
+## Prerequisites
+
+On Ubuntu:
+
+ * `sudo apt-get install golang git-all build-essential curl unzip`
+
+On Mac:
+
+ * Install Xcode Command Line Tools
+ * `brew install golang`
+
+## Creating a new checkout
+
+The bootstrap procedure requires that you have Go 1.6 or newer and Git
+installed and on your PATH.  To create a new Fuchsia checkout in a directory
+called `fuchsia` run the following commands. The `fuchsia` directory should
+not exist before running these steps.
+
+```
+curl -s https://raw.githubusercontent.com/fuchsia-mirror/jiri/master/scripts/bootstrap_jiri | bash -s fuchsia
+cd fuchsia
+export PATH=`pwd`/.jiri_root/bin:$PATH
+jiri import fuchsia https://fuchsia.googlesource.com/manifest
+jiri update
+```
+
+### Working without altering your PATH
+
+If you don't like having to mangle your environment variables, and you want
+`jiri` to "just work" depending on your current working directory, there's a
+shim for that.
+
+```
+sudo cp .jiri_root/bin/jiri /usr/local/bin
+sudo chmod 755 /usr/local/bin/jiri
+```
+
+That script is just a wrapper around the real `jiri`.  It crawls your parent
+directory structure until it finds a `.jiri_root` directory, then executes the
+`jiri` it finds there.

getting_started.md

-# Fuchsia
+Fuchsia
+============
 
 Pink + Purple == Fuchsia (a new Operating System)
 
@@ -8,8 +9,8 @@ Fuchsia.
 
 ## Getting the source
 Get the Fuchsia source by following these two steps and then return to this document:
-  * [Install prerequisites](https://fuchsia.googlesource.com/manifest/+/HEAD/README.md#Prerequisites) for Jiri, a tool for multi-repo development.
-  * [Create a new checkout](https://fuchsia.googlesource.com/manifest/+/HEAD/README.md#Creating-a-new-checkout) of Fuchsia.
+  * [Install prerequisites](https://fuchsia.googlesource.com/docs/+/HEAD/getting_source.md#Prerequisites) for Jiri, a tool for multi-repo development.
+  * [Create a new checkout](https://fuchsia.googlesource.com/docs/+/HEAD/getting_source.md#Creating-a-new-checkout) of Fuchsia.
 
 ## Prerequisites
 
@@ -169,14 +170,17 @@ frun -N -u $FUCHSIA_SCRIPTS_DIR/start-dhcp-server.sh
 The `-u` flag runs a script that sets up a local DHCP server and NAT to
 configure the IPv4 interface and routing.
 
-### Run Fuchsia on hardware
+### Running Fuchsia on hardware
 
 * [Acer Switch Alpha 12](https://fuchsia.googlesource.com/magenta/+/master/docs/targets/acer12.md)
 * [Intel NUC](https://fuchsia.googlesource.com/magenta/+/master/docs/targets/nuc.md)
 * [Raspberry Pi 3](https://fuchsia.googlesource.com/magenta/+/master/docs/targets/rpi3.md)
 
+## Contributing changes
+* See [contributing.md](https://fuchsia.googlesource.com/docs/+/HEAD/contributing.md).
+
 ## Additional helpful documents
 
 * [Fuchsia documentation](https://fuchsia.googlesource.com/docs) hub.
-* [Contributing changes](https://fuchsia.googlesource.com/manifest/+/HEAD/README.md#Submitting-changes).
+* Building [Fuchsia's toolchain](https://fuchsia.googlesource.com/docs/+/HEAD/building_toolchain.md)
 * More about the [build commands](build_system.md) called under-the-hood by `fbuild`.