[docs] Improve CONTRIBUTING documentation

[ci skip]

CONTRIBUTING.md

@@ -9,11 +9,14 @@ This project adheres to a [Code of Conduct][code-of-conduct]. By participating,
 
 You will need:
 
-1. Go 1.9+
+1. Go 1.11+
 1. Ruby 1.9+ with Bundler
 2. git 1.8+
 3. tmux & zsh (optional) - for running shell completion tests
 
+If setting up either Go or Ruby for development proves to be a pain, you can
+run the test suite in a prepared Docker container via `script/docker`.
+
 ## What makes a good hub feature
 
 hub is a tool that wraps git to provide useful integration with GitHub. A new
@@ -28,7 +31,7 @@ feature is a good idea for hub if it improves some workflow for a GitHub user.
 
 ## How to install dependencies and run tests
 
-1. [Clone the project](./README.md#source) into your GOPATH
+1. [Clone the project](./README.md#source)
 2. Verify that existing tests pass:
     `make test-all`
 3. Create a topic branch:
@@ -49,23 +52,8 @@ dependency.
 
 ## How to write tests
 
-The new test suite is written in Cucumber under `features/` directory. Each
-scenario is actually making real invocations to `hub` on the command-line in the
-context of a real (dynamically created) git repository.
-
-Whenever a scenario requires talking to the GitHub API, a fake HTTP server is
-spun locally to replace the real GitHub API. This is done so that the test suite
-runs faster and is available offline as well. The fake API server is defined
-as a Sinatra app inline in each scenario:
-
-```
-Given the GitHub API server:
-  """
-  post('/repos/github/hub/pulls') {
-    status 200
-  }
-  """
-```
+Go unit tests are in `*_test.go` files and are runnable with `make test`. These
+run really fast (under 10s).
 
-The best way to learn to write new tests is to study the existing scenarios for
-commands that are similar to those that you want to add or change.
+However, most hub functionality is exercised through integration-style tests
+written in Cucumber. See [Features](./features) for more info.

features/README.md

+# Cucumber features for hub
+
+How to run all features:
+
+```sh
+make bin/cucumber
+bin/cucumber
+```
+
+Because this can take a couple of minutes, you may want to only run select files
+related to the functionality that you're developing:
+
+```sh
+bin/cucumber feature/api.feature
+```
+
+The Cucumber test suite requires a Ruby development environment. If you want to
+avoid setting that up, you can run tests inside a Docker container:
+
+```sh
+script/docker feature/api.feature
+```
+
+## How it works
+
+Each scenario is actually making real invocations to `hub` on the command-line
+in the context of a real (dynamically created) git repository.
+
+Whenever a scenario requires talking to the GitHub API, a fake HTTP server is
+spun locally to replace the real GitHub API. This is done so that the test suite
+runs faster and is available offline as well. The fake API server is defined
+as a Sinatra app inline in each scenario:
+
+```
+Given the GitHub API server:
+  """
+  post('/repos/github/hub/pulls') {
+    status 200
+  }
+  """
+```
+
+## How to write new tests
+
+The best way to learn to write new tests is to study the existing scenarios for
+commands that are similar to those that you want to add or change.
+
+Since Cucumber tests are written in a natural language, you mostly don't need to
+know Ruby to write new tests.