Merge pull request #2260 from coreos-inc/STORY-136707589-test-pivotal-gh-integration

doc(README): add pivotal-gh integration help [Finishes #136707589]

README.md

@@ -2,7 +2,7 @@
 
 ![Docker Repository on Quay](https://quay.io/repository/quay/quay/status?token=7bffbc13-8bb0-4fb4-8a70-684a0cf485d3 "Docker Repository on Quay")
 
-**Note**: The `master` branch may be in an *unstable or even broken state* during development.
+:warning: The `master` branch may be in an *unstable or even broken state* during development.
 Please use [releases] instead of the `master` branch in order to get stable binaries.
 
 ![Quay Logo](static/img/quay_preview.png)
@@ -43,6 +43,32 @@ High-level features include:
 [Clair]: https://github.com/coreos/clair
 [Swagger]: http://swagger.io
 
+## Table of Contents
+
+1. **[Getting Started](#getting-started)**
+  1. [macOS](#macos)
+  3. [Linux](#linux)
+2. **[Development](#development)**
+  1. [PivotalTracker Integration](#pivotaltracker-integration)
+3. **[Running and Testing](#running-and-testing)**
+  1. [Test Data](#test-data)
+  2. [Local Scripts](#local-scripts)
+  3. [Development inside Docker](#development-inside-docker)
+  4. [Adding a Python Dependency](#adding-a-python-dependency)
+  5. [Running the Build System](#running-the-build-system)
+  6. [To run individual tests](#to-run-individual-tests)
+    1. [Pytest](#pytest)
+    2. [Tox](#tox)
+  7. [Running Migrations](#running-migrations)
+  8. [How to run a build with tests for a push or merge](#how-to-run-a-build-with-tests-for-a-push-or-merge)
+4. **[Documentation](#documentation)**
+  1. [Architecture at a Glance](#architecture-at-a-glance)
+  2. [Terminology](#terminology)
+    1. [Organizations](#organizations)
+    2. [Concepts](#concepts)
+    3. [Software](#software)
+
+
 ## Getting Started
 
 ### macOS
@@ -98,29 +124,51 @@ npm install
 npm link typescript
 ```
 
-### Useful docs
+#### Useful docs
+
+* [docker](https://beta.docker.com/docs/mac/getting-started://beta.docker.com/docs/mac/getting-started)
+* [docker-machine](https://docs.docker.com/machine/install-machine://docs.docker.com/machine/install-machine)
+* [pyenv](https://github.com/yyuu/pyenv)
+* [pyenv-virtualenv](https://github.com/yyuu/pyenv-virtualenv)
 
-[docker](https://beta.docker.com/docs/mac/getting-started://beta.docker.com/docs/mac/getting-started)
-[docker-machine](https://docs.docker.com/machine/install-machine://docs.docker.com/machine/install-machine)
-[pyenv](https://github.com/yyuu/pyenv)
-[pyenv-virtualenv](https://github.com/yyuu/pyenv-virtualenv)
 
 
 ### Linux
 
 TODO
 
+## Development
+
+### PivotalTracker Integration
+
+Tag a commit with the Tracker Story ID and GitHub automatically comments on your
+story with the commit message.
+
+Add the following at the end of your commit message:
+
+```
+[(Finishes|Fixes|Delivers) #TRACKER_STORY_ID]
+```
+
+When you push to GitHub, the post-receive hook will then call back to Tracker
+and put a comment on the story with a link to the commit on GitHub. When tagged
+with "Finishes", the trigger will also click Finish on the story.
+
+Reference: PivotalTracker blog - [A Guide to GitHub’s Service Hook for Tracker](https://www.pivotaltracker.com/blog/guide-githubs-service-hook-tracker/)
+
+
 ## Running and Testing
 
 ### Test Data
 
-A SQLite database full of test data is committed to this git repository at `test/data/test.db`.
+A SQLite database full of test data is committed to this git repository at [test/data/test.db](quay/test/data/test.db).
 This database is generated by executing `python initdb.py`.
 The username and password of the admin test account is `devtable` and `password`, respectively.
 
 ### Local Scripts
 
 Running the web server locally requires [goreman](https://github.com/mattn/goreman):
+
 ```
 go get github.com/mattn/goreman
 ```
@@ -132,7 +180,7 @@ go get github.com/mattn/goreman
 
 ### Development inside Docker
 
-To build and run a development container, pass one argument to local-docker.sh:
+To build and run a development container, pass one argument to [local-docker.sh](quay/local-docker.sh):
 
 - `buildman`: run the buildmanager
 - `dev`: run web server on port 5000
@@ -252,7 +300,12 @@ docker build -t $QUAY_TAG --build-arg RUN_TESTS=true .
 * [Quay Enterprise Documentation](https://tectonic.com/quay-enterprise/docs/latest)
 * [Quay.io Documentation](https://docs.quay.io)
 
-### [Architecture at a Glance](https://docs.google.com/a/coreos.com/drawings/d/1J-YZs7aun1lLy-1wFwIZcBma5IJmZQ8WfgtEftHCKJ0/edit?usp=sharing)
+### Architecture at a Glance
+
+<img src="https://docs.google.com/a/coreos.com/drawings/d/1J-YZs7aun1lLy-1wFwIZcBma5IJmZQ8WfgtEftHCKJ0/pub?w=640&amp;h=480">
+
+Edit chart on Google Docs at [Architecture at a Glance](https://docs.google.com/a/coreos.com/drawings/d/1J-YZs7aun1lLy-1wFwIZcBma5IJmZQ8WfgtEftHCKJ0/edit?usp=sharing).
+
 
 ### Terminology