Merge pull request #256 from arschles/readme-beta

docs(README.md): update docs to match beta status

Author: arschles

README.md

@@ -2,95 +2,79 @@
 
 [![Build Status](https://travis-ci.org/deis/builder.svg?branch=master)](https://travis-ci.org/deis/builder) [![Go Report Card](http://goreportcard.com/badge/deis/builder)](http://goreportcard.com/report/deis/builder) [![Docker Repository on Quay](https://quay.io/repository/deisci/builder/status "Docker Repository on Quay")](https://quay.io/repository/deisci/builder)
 
-Deis (pronounced DAY-iss) is an open source PaaS that makes it easy to deploy and manage
-applications on your own servers. Deis builds on [Kubernetes](http://kubernetes.io/) to provide
-a lightweight, [Heroku-inspired](http://heroku.com) workflow.
+Deis (pronounced DAY-iss) is an open source PaaS that makes it easy to deploy and manage applications on your own servers. Deis builds on [Kubernetes][k8s-home] to provide a lightweight, easy and secure way to deploy your code to production.
 
-## Work in Progress
+For more information about the Deis workflow, please visit the main project page at https://github.com/deis/workflow.
 
-![Deis Graphic](https://s3-us-west-2.amazonaws.com/get-deis/deis-graphic-small.png)
+## Beta Status
 
-Deis Builder v2 is changing quickly. Your feedback and participation are more than welcome, but be
-aware that this project is considered a work in progress.
+This Deis component is currently in beta status, and we welcome your input! If you have feedback, please [submit an issue][issues]. If you'd like to participate in development, please read the "Development" section below and [submit a pull request][prs].
 
 # About
 
-This package provides a the Deis Builder, a git server to respond to `git push`es from clients. When it receives a push, it takes the following high level steps:
+The builder is primarily a git server that responds to `git push`es by executing either the `git-receive-pack` or `git-upload-pack` hook. After it executes one of those hooks, it takes the following high level steps in order:
 
-1. Accepts the code and writes to the local file system
-2. Calls `git archive` to produce a tarball (i.e. a `.tar.gz` file) on the local file system
-3. Saves the tarball according to the following rules:
-  - If the `DEIS_MINIO_SERVICE_HOST` and `DEIS_MINIO_SERVICE_PORT` environment variables exist, uses the [`mc`](https://github.com/minio/mc) client to save to the [Minio](https://github.com/minio/minio) server at `http://$DEIS_MINIO_SERVICE_HOST:$DEIS_MINIO_SERVICE_HOST`
-  - Otherwise, if the `DEIS_OUTSIDE_STORAGE_HOST` and `DEIS_OUTSIDE_STORAGE_PORT` environment variables exist, uses the [`mc`](https://github.com/minio/mc) client to save to S3 server (or server that adheres to the S3 API) at `https://$DEIS_OUTSIDE_STORAGE_HOST:$DEIS_OUTSIDE_STORAGE_PORT` (this functionality is currently waiting for merge at https://github.com/deis/builder/pull/21).
-4. Starts a builder pod according to these rules:
-  - If a `Dockerfile` is present, starts a [`dockerbuilder`](https://github.com/deis/dockerbuilder) pod, configured to download the code to build from the URL computed in the previous step (`dockerbuilder` and Dockerfile builder are not currently supported. See https://github.com/deis/dockerbuilder/pull/1 for prototype `dockerbuilder` code).
+1. Calls `git archive` to produce a tarball (i.e. a `.tar.gz` file) on the local file system
+2. Saves the tarball to centralized object storage according to the following rules:
+	- If the `DEIS_OUTSIDE_STORAGE` environment variable exists, saves to the [S3 API][s3-api-ref] compatible server at `https://$DEIS_OUTSIDE_STORAGE`
+  - Otherwise, if the `DEIS_MINIO_SERVICE_HOST` and `DEIS_MINIO_SERVICE_PORT` environment variables exist (these are standard [Kubernetes service discovery environment variables](http://kubernetes.io/docs/user-guide/services/#environment-variables)), saves to the [S3 API][s3-api-ref] compatible server at `http://$DEIS_MINIO_SERVICE_HOST:$DEIS_MINIO_SERVICE_HOST`
+3. Starts a new [Kubernetes Pod](http://kubernetes.io/docs/user-guide/pods/) to build the code, according to the following rules:
+  - If a `Dockerfile` is present in the codebase, starts a [`dockerbuilder`](https://github.com/deis/dockerbuilder) pod, configured to download the code to build from the URL computed in the previous step.
   - Otherwise, starts a [`slugbuilder`](https://github.com/deis/slugbuilder) pod, configured to download the code to build from the URL computed in the previous step.
 
-# Hacking Builder
+# Development
 
-First, install [helm](http://helm.sh) and [boot up a kubernetes cluster][install-k8s]. Next, add the
-`deis` repository to your chart list:
+The Deis project welcomes contributions from all developers. The high level process for development matches many other open source projects. See below for an outline.
 
-```console
-$ helm repo add deis https://github.com/deis/charts
-```
+* Fork this repository
+* Make your changes
+* [Submit a pull request][prs] (PR) to this repository with your changes, and unit tests whenever possible.
+	* If your PR fixes any [issues][issues], make sure you write `Fixes #1234` in your PR description (where `#1234` is the number of the issue you're closing)
+* The Deis core contributors will review your code. After each of them sign off on your code, they'll label your PR with `LGTM1` and `LGTM2` (respectively). Once that happens, you may merge.
 
-Then, install the Deis chart!
+## Docker Based Development Environment
 
-```console
-$ helm install deis/deis
-```
+The preferred environment for development uses [the `go-dev` Docker image](https://github.com/deis/docker-go-dev). The tools described in this section are used to build, test, package and release each version of Deis.
 
-The chart will install the entire Deis platform onto Kubernetes. You can monitor all the pods that it installs by running:
+To use it yourself, you must have [make](https://www.gnu.org/software/make/) installed and Docker installed and running on your local development machine.
 
-```console
-$ kubectl get pods --namespace=deis
-```
+If you don't have Docker installed, please go to https://www.docker.com/ to install it.
 
-Once this is done, SSH into a Kubernetes minion, and run the following:
+After you have those dependencies, build your code with `make build` and execute unit tests with `make test`.
 
-```
-$ curl -sSL http://deis.io/deis-cli/install.sh | sh
-$ sudo mv deis /bin
-$ kubectl get service deis-controller
-$ deis register 10.247.59.157 # or the appropriate CLUSTER_IP
-$ ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
-$ eval $(ssh-agent) && ssh-add ~/.ssh/id_rsa
-$ deis keys:add ~/.ssh/id_rsa.pub
-$ deis create --no-remote
-Creating Application... done, created madras-radiator
-$ deis pull deis/example-go -a madras-radiator
-Creating build... ..o
-```
+## Native Go Development Environment
 
-If you want to hack on a new feature, rebuild your code, build the deis/builder image and push it to a Docker registry. The `$DEIS_REGISTRY` environment variable must point to a registry accessible to your Kubernetes cluster. If you're using a locally hosted Docker registry, you may need to configure the Docker engines on your Kubernetes nodes to allow `--insecure-registry 192.168.0.0/16` (or the appropriate address range).
+You can also use the standard `go` toolchain to build and test if you prefer. To do so, you'll need [glide](https://github.com/Masterminds/glide) 0.9 or above and [Go 1.6](http://golang.org) or above installed.
 
-```console
-$ make build docker-build docker-push
-```
+After you have those dependencies, you can build and unit-test your code with `go build` and `go test $(glide nv)`, respectively.
 
-Next, you'll want to remove the `deis-builder` [replication controller](http://kubernetes.io/v1.1/docs/user-guide/replication-controller.html) and re-create it to run your new image.
+Note that you will not be able to build or push Docker images using this method of development.
 
-```console
-kubectl delete --namespace=deis rc deis-builder
-make kube-rc
-```
+# Testing
 
-## Installation
+The Deis project requires that as much code as possible is unit tested, but the core contributors also recognize that some code must be tested at a higher level (functional or integration tests, for example).
 
-The following steps assume that you have the [Docker CLI](https://docs.docker.com/) and [Kubernetes CLI](http://kubernetes.io/v1.1/docs/user-guide/kubectl-overview.html) installed and correctly configured.
+The [end-to-end tests](https://github.com/deis/workflow-e2e) repository has our integration tests. Additionally, the core contributors and members of the community also regularly [dogfood](https://en.wikipedia.org/wiki/Eating_your_own_dog_food) the platform. Since this particular component is at the center of much of the Deis platform, we find it especially important to dogfood it.
 
-```
-make deploy kube-service
-```
+## Running End-to-End Tests
 
-## License
+Please see [README.md](https://github.com/deis/workflow-e2e/blob/master/README.md) on the end-to-end tests reposotory for instructions on how to set up your testing environment and run the tests.
 
-Copyright 2013, 2014, 2015 Engine Yard, Inc.
+## Dogfooding
+
+Please follow the instructions on the [official Deis docs](http://docs-v2.readthedocs.org/en/latest/installing-workflow/installing-deis-workflow/) to install and configure your Deis cluster and all related tools, and deploy and configure an app on Deis.
+
+# License
+
+Copyright 2013, 2014, 2015, 2016 Engine Yard, Inc.
 
 Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at <http://www.apache.org/licenses/LICENSE-2.0>
 
 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 
 
+[s3-api-ref]: http://docs.aws.amazon.com/AmazonS3/latest/API/APIRest.html
 [install-k8s]: http://kubernetes.io/gettingstarted/
+[k8s-home]: http://kubernetes.io
+[issues]: https://github.com/deis/builder/issues
+[prs]: https://github.com/deis/builder/pulls