docs(hacking): simplify and clarify a bit

docs/hacking.md

@@ -1,141 +1,126 @@
 # Hacking on Prow
 
-This document is for developers who are interested in working directly on the Prow codebase. In
-this guide, we walk you through the process of setting up a development environment that is
-suitable for hacking on Prow.
+This guide is for developers who want to improve Prow. These instructions will help you set up a
+development environment for working on the Prow source code.
 
 ## Prerequisites
 
-In order to successfully compile and test Prow binaries and build Docker images of Prowd, the
-following are required:
+To compile and test Prow binaries and to build Docker images, you will need:
 
- - [git](https://git-scm.com/)
- - [Go](https://golang.org/) 1.7 or later, with support for compiling to `linux/amd64`
- - [glide](https://github.com/Masterminds/glide)
- - [docker](https://www.docker.com/)
- - a Kubernetes cluster. We recommend [minikube](https://github.com/kubernetes/minikube)
- - [helm](https://github.com/kubernetes/helm)
- - [upx](https://upx.github.io) OPTIONAL if you want to compress your binary for smaller Docker images.
+ - [docker][]
+ - [git][]
+ - [Go][] 1.7 or later, with support for compiling to `linux/amd64`
+ - [glide][]
+ - a [Kubernetes][] cluster. We recommend [minikube][]
+ - [helm][]
+ - [upx][] (optional) to compress binaries for a smaller Docker image
 
-In most cases, you should simply install according to the instructions. We'll cover the special
-cases below.
+In most cases, install the prerequisite according to its instructions. See the next section
+for a note about Go cross-compiling support.
 
 ### Configuring Go
 
-If your local workstation does not support the `linux/amd64` target environment, you will have to
-install Go from source with cross-compile support for that environment. This is because some of the
-components are built on your local machine and then injected into a Docker container.
+Prow's binary executables are built on your machine and then copied into a Docker image. This
+requires your Go compiler to support the `linux/amd64` target architecture. If you develop on a
+machine that isn't AMD64 Linux, make sure that `go` has support for cross-compiling.
 
-Homebrew users can just install with cross compiling support:
+On macOS, a cross-compiling Go can be installed with [Homebrew][]:
 
-```
+```shell
 $ brew install go --with-cc-common
 ```
 
 It is also straightforward to build Go from source:
 
-```
+```shell
 $ sudo su
 $ curl -sSL https://storage.googleapis.com/golang/go1.7.5.src.tar.gz | tar -C /usr/local -xz
 $ cd /usr/local/go/src
-$ # compile Go for our default platform first, then add cross-compile support
+$ # compile Go for the default platform first, then add cross-compile support
 $ ./make.bash --no-clean
 $ GOOS=linux GOARCH=amd64 ./make.bash --no-clean
 ```
 
-Once you can compile to `linux/amd64`, you should be able to compile Prowd for preparation into a
-Docker image.
-
 ## Fork the Repository
 
-Once the prerequisites have been met, we can begin to work with Prow.
+Begin at Github by forking Prow, then clone your fork locally. Since Prow is a Go package, it
+should be located at `$GOPATH/src/github.com/deis/prow`.
 
-Begin at Github by forking Prow, then clone that fork locally. Since Prow is written in Go, the
-best place to put it is under `$GOPATH/src/github.com/deis/`.
-
-```
+```shell
 $ mkdir -p $GOPATH/src/github.com/deis
 $ cd $GOPATH/src/github.com/deis
 $ git clone git@github.com:<username>/prow.git
 $ cd prow
 ```
 
-If you are going to be issuing pull requests to the upstream repository from which you forked, we
-suggest configuring git such that you can easily rebase your code to the upstream repository's
-master branch. There are various strategies for doing this, but the
-[most common](https://help.github.com/articles/fork-a-repo/) is to add an `upstream` remote:
+Add the conventional [upstream][] `git` remote in order to fetch changes from Prow's main master
+branch and to create pull requests:
 
-```
+```shell
 $ git remote add upstream https://github.com/deis/prow.git
 ```
 
-## Make Your Changes
+## Build Your Changes
 
-With your development environment set up and the code you wish to work on forked and cloned, you
-can begin making your changes.
+With the prerequisites installed and your fork of Prow cloned, you can make changes to local Prow
+source code.
 
-To do that, run the following to get your environment ready:
+Run `make` to build the `prow` and `prowd` binaries:
 
-```
+```shell
 $ make bootstrap  # runs `glide install`
 $ make build      # compiles `prow` and `prowd` inside bin/
 ```
 
 ## Test Your Changes
 
-Prow includes a comprehensive suite of tests. To run these tests, run `make test`.
-
-If you wish to run a more extensive set of tests, run `make test-e2e`.
+Prow includes a suite of tests. Run `make test` for basic unit tests or `make test-e2e` for more
+comprehensive, end-to-end tests.
 
 ## Deploying Your Changes
 
-Although writing and executing tests are critical to ensuring code quality, you will likely want to
-deploy changes to a live environment, whether to make use of those changes or to test them further.
+To test interactively, you will likely want to deploy your changes to Prow on a Kubernetes cluster.
+This requires a Docker registry where you can push your customized Prowd images so Kubernetes can
+pull them.
 
-To facilitate deploying Prowd images containing your changes to your Kubernetes cluster, you will
-need to make use of a Docker Registry. This is a location to where you can push your custom-built
-images and from where your Kubernetes cluster can retrieve those same images.
+In most cases, a local Docker registry will not be accessible to your Kubernetes nodes. A public
+registry such as [Docker Hub][] or [Quay][] will suffice.
 
-In most cases, a local registry will not be accessible to your Kubernetes nodes. A public registry
-such as [Docker Hub](https://hub.docker.com/) or [Quay][https://quay.io/] will suffice.
+To use DockerHub for Prowd images:
 
-To use DockerHub for this purpose, for instance:
-
-```
+```shell
 $ export DOCKER_REGISTRY="docker.io"
 $ export IMAGE_PREFIX=<your DockerHub username>
 ```
 
 To use quay.io:
 
-```
+```shell
 $ export DOCKER_REGISTRY="quay.io"
 $ export IMAGE_PREFIX=<your quay.io username>
 ```
 
-After your Docker Registry is set up, you can deploy your images using
+After your Docker registry is set up, you can deploy your images using:
 
-```
+```shell
 $ make docker-build docker-push
 ```
 
-To install Prowd, edit `chart/values.yaml` and change the `registry` and `name` values to the image
-you just deployed:
+Ensure that Helm's `tiller` server is running in the Kubernetes cluster:
 
-```
-$ $EDITOR charts/values.yaml
+```shell
+$ helm init  # it may take a few seconds for tiller to install
+$ helm version
+Client: &version.Version{SemVer:"v2.2.0", GitCommit:"fc315ab59850ddd1b9b4959c89ef008fef5cdf89", GitTreeState:"clean"}
+Server: &version.Version{SemVer:"v2.2.0", GitCommit:"fc315ab59850ddd1b9b4959c89ef008fef5cdf89", GitTreeState:"clean"}
 ```
 
-Ensure Tiller is running in the Kubernetes cluster:
+Then, install the Prow chart. Make sure to override `values.yaml` with flags that reference your
+Prowd image:
 
-```
-$ helm init
-```
-
-Then, install the chart:
-
-```
-$ helm install ./chart --name prow --namespace prow
+```shell
+$ helm install ./chart --name prow --namespace prow \
+    --set image.registry=$DOCKER_REGISTRY,image.name=$IMAGE_PREFIX/prowd
 ```
 
 You should see a new Helm release available in `helm list`.
@@ -147,7 +132,7 @@ use Prow to deploy Prow. How neat is that?!
 
 To build your changes and upload it to Prowd, run
 
-```
+```shell
 $ make build docker-binary
 $ prow up
 --> Building Dockerfile
@@ -157,3 +142,17 @@ $ prow up
 ```
 
 You should see a new release of Prow available and deployed with `helm list`.
+
+
+[docker]: https://www.docker.com/
+[Docker Hub]: https://hub.docker.com/
+[git]: https://git-scm.com/
+[glide]: https://github.com/Masterminds/glide
+[go]: https://golang.org/
+[helm]: https://github.com/kubernetes/helm
+[Homebrew]: https://brew.sh/
+[Kubernetes]: https://github.com/kubernetes/minikube
+[minikube]: https://github.com/kubernetes/minikube
+[Quay]: https://quay.io/
+[upstream]: https://help.github.com/articles/fork-a-repo/
+[upx]: https://upx.github.io