From e2aa095680271e51e8d3a74633293580cbfb49bf Mon Sep 17 00:00:00 2001
From: Eric Chiang <eric.chiang@coreos.com>
Date: Wed, 7 Dec 2016 13:16:56 -0800
Subject: [PATCH] Documentation: add document on managing dependencies

---
 Documentation/dev-dependencies.md | 36 +++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)
 create mode 100644 Documentation/dev-dependencies.md

diff --git a/Documentation/dev-dependencies.md b/Documentation/dev-dependencies.md
new file mode 100644
index 00000000..ea63e420
--- /dev/null
+++ b/Documentation/dev-dependencies.md
@@ -0,0 +1,36 @@
+# Managing dependencies
+
+Dex uses [glide][glide] and [glide-vc][glide-vc] to manage its [`vendor` directory][go-vendor]. A recent version of these are preferred but dex doesn't require any bleeding edge features. Either install these tools using `go get` or take an opportunity to update to a more recent version.
+
+```
+go get -u github.com/Masterminds/glide
+go get -u github.com/sgotti/glide-vc
+```
+
+To add a new dependency to dex or update an existing one:
+
+* Make changes to dex's source code importing the new dependency.
+* Edit `glide.yaml` to include the new dependency at a given commit SHA or change a SHA.
+* Add all transitive dependencies of the package to prevent unpinned packages.
+
+Tests will fail if transitive dependencies aren't included. 
+
+Once `glide.yaml` describes the desired state use glide and glide-vc to update `glide.lock` and `vendor`.
+
+```
+glide up -v
+glide-vc
+```
+
+When composing commits make sure that updates to `vendor` are in a separate commit from the main changes. GitHub's UI makes commits with a large number of changes unreviewable.
+
+Commit histories should look like the following:
+
+```
+connector/ldap: add a LDAP connector
+vendor: revendor
+```
+
+[glide]: https://github.com/Masterminds/glide
+[glide-vc]: https://github.com/sgotti/glide-vc
+[go-vendor]: https://golang.org/cmd/go/#hdr-Vendor_Directories