Improve experience for on-boarding new developers

.travis.yml

@@ -2,5 +2,4 @@ language: go
 go:
   - 1.6
   - 1.7
-install: make deps
 after_success: make perf-regression

Makefile

@@ -38,12 +38,10 @@ export GO15VENDOREXPERIMENT
 
 .PHONY: all deps generate build install test perf perf-regression cover check check-fmt check-vet check-lint fmt clean
 
-all: build test check
+all: deps build test check
 
 deps:
-	$(GO) install ./vendor/github.com/PuerkitoBio/pigeon
-	$(GO) install ./vendor/golang.org/x/tools/cmd/goimports
-	$(GO) install ./vendor/github.com/golang/lint/golint
+	@./build/install-deps.sh
 
 generate:
 	$(GO) generate

README.md

@@ -1,10 +1,16 @@
 # OPA: Open Policy Agent
 
-The Open Policy Agent (OPA) is an open source project that helps policy-enable your service.
-By integrating with OPA, your service's operators will be empowered to manage the size,
-complexity, and scale of modern deployments.
+The Open Policy Agent (OPA) is an open source project that helps policy-enable your service. By integrating with OPA, your service's operators will be empowered to manage the size, complexity, and dynamic nature of modern deployments.
 
-To learn more and get started, visit [openpolicyagent.org](http://www.openpolicyagent.org).
+To learn more, visit [openpolicyagent.org](http://www.openpolicyagent.org).
+
+## Want to use OPA?
+
+See [Get OPA](http://www.openpolicyagent.org/get-opa/) for download links.
+
+## Want to build OPA?
+
+See [DEVELOPMENT.md](./docs/DEVELOPMENT.md) for development environment setup and build instructions.
 
 ## Helpful Links
 

build/check-lint.sh

@@ -12,7 +12,6 @@ function opa::check_lint() {
     exec 5>&1
     exit_code=0
     for pkg in $(opa::go_packages); do
-        echo $pkg
         __output=$(golint $pkg | tee >(cat - >&5))
         if [ ! -z "$__output" ]; then
             exit_code=1

build/install-deps.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+
+set -e
+
+if [ -z "$GOPATH" ]; then
+	echo '$GOPATH environment variable not set. Have you installed Go?'
+	exit 1
+fi
+
+which pigeon >/dev/null || {
+	echo "Installing pigeon from vendor"
+	go install ./vendor/github.com/PuerkitoBio/pigeon
+}
+
+
+which goimports >/dev/null || {
+	echo "Installing goimports from vendor"
+	go install ./vendor/golang.org/x/tools/cmd/goimports
+}
+
+which golint >/dev/null || {
+	echo "Installing golint from vendor"
+	go install ./vendor/github.com/golang/lint/golint
+}

docs/DEVELOPMENT.md

@@ -19,21 +19,24 @@ Requirements:
 - Go (version 1.6.x and 1.7.x are supported)
 - GNU Make
 
-## Getting Started
+## <a name="Getting-Started"></a> Getting Started
 
-After cloning the repository, run `make deps` to install the parser generator ("pigeon") into your workspace.
+After cloning the repository, just run `make`. This will:
 
-Next, run `make all` to build the project, execute all of the tests, and run
-static analysis checks against the code. If this succeeds, there should be a
-new binary in the top level directory ("opa").
+- Install required dependencies, e.g., the parser-generator ("pigeon").
+- Build the OPA binary.
+- Run all of the tests.
+- Run all of the static analysis checks.
 
-Verify the build was successful by running `opa version`.
+If the build was successful, a binary will be produced in the top directory (`opa_<OS>_<ARCH>`).
+
+Verify the build was successful with `./opa_<OS>_<ARCH> run`.
 
 You can re-build the project with `make build`, execute all of the tests
 with `make test`, and execute all of the performance benchmarks with `make perf`.
 
-The static analysis checks (i.e., `go fmt`, `golint`, and `go vet` can be run
-with `make check`).
+The static analysis checks (e.g., `go fmt`, `golint`, `go vet`) can be run
+with `make check`.
 
 ## Workflow