From 75a5362d46be5db14a34214a50784c76cf2f4da1 Mon Sep 17 00:00:00 2001
From: Eric Chiang <eric.chiang.m@gmail.com>
Date: Mon, 25 Jan 2016 20:17:34 -0800
Subject: [PATCH] Documentation: add section about using godeps

---
 Documentation/dev-guide.md | 71 ++++++++++++++++++++++++++++++++++++++
 schema/generator_import.go | 10 +++---
 2 files changed, 75 insertions(+), 6 deletions(-)

diff --git a/Documentation/dev-guide.md b/Documentation/dev-guide.md
index ef3da133..5d346db6 100644
--- a/Documentation/dev-guide.md
+++ b/Documentation/dev-guide.md
@@ -79,3 +79,74 @@ DOCKER_LINKS=dex_postgres:postgres DOCKER_ENV=DEX_TEST_DSN ./go-docker ./test-fu
 # Remove the container after the tests are run.
 docker rm -f dex_postgres
 ```
+
+## Vendoring dependencies
+
+dex uses [godep](https://github.com/tools/godep) for vendoring external dependencies. This section details how to add and update those dependencies.
+
+Before continuing, please ensure you have the **latest version** of godep available in your PATH.
+
+```
+go get -u github.com/tools/godep
+```
+
+### Preparing your GOPATH
+
+Godep assumes code uses the [standard Go directory layout](https://golang.org/doc/code.html#Organization) with the GOPATH environment variable. Developers who use a different workflow (for instance, prefer working from `~/src/dex`) should see [rkt's documentation](https://github.com/coreos/rkt/blob/master/Documentation/hacking.md#having-the-right-directory-layout-ie-gopath) for workarounds.
+
+Godep determines depdencies using the GOPATH, not the vendored code in the Godeps directory. The first step is to "restore" your GOPATH to match the vendored state of dex. From dex's top level directory run:
+
+```
+godep restore -v
+```
+
+Next, continue to either *Adding a new package* or *Updating an existing package*.
+
+### Adding a new package
+
+After adding a new `import` to dex source, godep will automatically detect it and update the vendored code. Once code changes are finalized, bring the dependency into your GOPATH and save the state:
+
+```
+go get github.com/mavricknz/ldap # Replace with your dependency.
+godep save ./...
+```
+
+Note that dex does **not** rewrite import paths like other CoreOS projects.
+
+## Updating an existing package
+
+After restoring your GOPATH, update the dependency in your GOPATH to the version you wish to check in.
+
+```
+cd $GOPATH/src/github.com/lib/pq # Replace with your dependency.
+git checkout origin master
+```
+
+Then, move to dex's top level directory and run:
+
+```
+godep update github.com/lib/pq
+```
+
+To update a group of packages, use the `...` notation.
+
+```
+godep update github.com/coreos/go-oidc/...
+```
+
+## Finalizing your change
+
+Use git to ensure the Godeps directory has updated only your target packages.
+
+Changes to the Godeps directory should be added as a separate commit from other changes for readability:
+
+```
+git status      # make sure things look reasonable
+git add Godeps
+git commit -m "Godeps: updated postgres driver"
+
+# continue working
+
+git add .
+git commit -m "dirname: this is my actual change"
+```
diff --git a/schema/generator_import.go b/schema/generator_import.go
index 09e9419a..96d14349 100644
--- a/schema/generator_import.go
+++ b/schema/generator_import.go
@@ -3,10 +3,8 @@ package schema
 // This file exists to ensure Godep manages a vendored copy of the
 // `google-api-go-generator` library, used by the 'generate' script.
 // Unfortunately since this is a binary package and hence is not importable, we
-// need to trick godep into managing it. To update the dependency, do the following steps:
-// 1. Uncomment the import line below
-// 2. Update the package in GOPATH as appropriate (e.g. `go get -u google.golang.org/api/google-api-go-generator`)
-// 3. Run `godep save` as usual across the entire project (e.g. `godep save ./...`)
-// 4. Revert this file (i.e. comment the line again, and revert to the original import) as it may not build properly
+// need to trick godep into managing it by providing an import statement.
 
-// import _ "google.golang.org/api/google-api-go-generator"
+// This file is not expected to build.
+
+import _ "google.golang.org/api/google-api-go-generator"