Breaking out README

Adding new material
Adding in template chomped in error
Cover install/deploy in README
Adding in Stephen's comments
Fixing you tabs!
Updating with commentary from pr
Updating with last minute comments

Signed-off-by: Mary Anthony <mary@docker.com>

docs/building.md

@@ -0,0 +1,123 @@
+page_title: Build the development environment
+page_description: Explains how to build the distribution project
+page_keywords: registry, service, images, repository
+
+# Build the development environment
+
+If a go development environment is setup, one can use `go get` to install the
+`registry` command from the current latest:
+
+```sh
+go get github.com/docker/distribution/cmd/registry
+```
+
+The above will install the source repository into the `GOPATH`. The `registry`
+binary can then be run with the following:
+
+```
+$ $GOPATH/bin/registry -version
+$GOPATH/bin/registry github.com/docker/distribution v2.0.0-alpha.1+unknown
+```
+
+The registry can be run with the default config using the following
+incantantation:
+
+```
+$ $GOPATH/bin/registry $GOPATH/src/github.com/docker/distribution/cmd/registry/config.yml
+INFO[0000] endpoint local-8082 disabled, skipping        app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown
+INFO[0000] endpoint local-8083 disabled, skipping        app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown
+INFO[0000] listening on :5000                            app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown
+INFO[0000] debug server listening localhost:5001
+```
+
+If it is working, one should see the above log messages.
+
+### Repeatable Builds
+
+For the full development experience, one should `cd` into
+`$GOPATH/src/github.com/docker/distribution`. From there, the regular `go`
+commands, such as `go test`, should work per package (please see
+[Developing](#developing) if they don't work).
+
+A `Makefile` has been provided as a convenience to support repeatable builds.
+Please install the following into `GOPATH` for it to work:
+
+```
+go get github.com/tools/godep github.com/golang/lint/golint
+```
+
+**TODO(stevvooe):** Add a `make setup` command to Makefile to run this. Have to think about how to interact with Godeps properly.
+
+Once these commands are available in the `GOPATH`, run `make` to get a full
+build:
+
+```
+$ GOPATH=`godep path`:$GOPATH make
++ clean
++ fmt
++ vet
++ lint
++ build
+github.com/docker/docker/vendor/src/code.google.com/p/go/src/pkg/archive/tar
+github.com/Sirupsen/logrus
+github.com/docker/libtrust
+...
+github.com/yvasiyarov/gorelic
+github.com/docker/distribution/registry/handlers
+github.com/docker/distribution/cmd/registry
++ test
+...
+ok    github.com/docker/distribution/digest 7.875s
+ok    github.com/docker/distribution/manifest 0.028s
+ok    github.com/docker/distribution/notifications  17.322s
+?     github.com/docker/distribution/registry [no test files]
+ok    github.com/docker/distribution/registry/api/v2  0.101s
+?     github.com/docker/distribution/registry/auth  [no test files]
+ok    github.com/docker/distribution/registry/auth/silly  0.011s
+...
++ /Users/sday/go/src/github.com/docker/distribution/bin/registry
++ /Users/sday/go/src/github.com/docker/distribution/bin/registry-api-descriptor-template
++ /Users/sday/go/src/github.com/docker/distribution/bin/dist
++ binaries
+```
+
+The above provides a repeatable build using the contents of the vendored
+Godeps directory. This includes formatting, vetting, linting, building,
+testing and generating tagged binaries. We can verify this worked by running
+the registry binary generated in the "./bin" directory:
+
+```sh
+$ ./bin/registry -version
+./bin/registry github.com/docker/distribution v2.0.0-alpha.2-80-g16d8b2c.m
+```
+
+### Developing
+
+The above approaches are helpful for small experimentation. If more complex
+tasks are at hand, it is recommended to employ the full power of `godep`.
+
+The Makefile is designed to have its `GOPATH` defined externally. This allows
+one to experiment with various development environment setups. This is
+primarily useful when testing upstream bugfixes, by modifying local code. This
+can be demonstrated using `godep` to migrate the `GOPATH` to use the specified
+dependencies. The `GOPATH` can be migrated to the current package versions
+declared in `Godeps` with the following command:
+
+```sh
+godep restore
+```
+
+> **WARNING:** This command will checkout versions of the code specified in
+> Godeps/Godeps.json, modifying the contents of `GOPATH`. If this is
+> undesired, it is recommended to create a workspace devoted to work on the
+> _Distribution_ project.
+
+With a successful run of the above command, one can now use `make` without
+specifying the `GOPATH`:
+
+```sh
+$ make
+```
+
+If that is successful, standard `go` commands, such as `go test` should work,
+per package, without issue.