Merge pull request #1369 from josdotso/go-modules-docs

Documentation/dev-dependencies.md: Update for Go modules
This commit is contained in:
Eric Chiang 2018-12-04 13:14:22 -08:00 committed by GitHub
commit 60264d440c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -1,25 +1,31 @@
# 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 modules
Dex uses [Go modules][go-modules] to manage its [`vendor` directory][go-vendor]. Go 1.11 or higher is recommended. While Go 1.12 is expected to finalize the Go modules feature, with Go 1.11 you should [activate the Go modules feature][go-modules-activate] before interacting with Go modules.
Here is one way to activate the Go modules feature with Go 1.11.
```
go get -u github.com/Masterminds/glide
go get -u github.com/sgotti/glide-vc
export GO111MODULE=on # manually active module mode
```
You should become familiar with [module-aware `go get`][module-aware-go-get] as it can be used to add version-pinned dependencies out of band of the typical `go mod tidy -v` workflow.
## Adding dependencies
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.
1. Make changes to dex's source code importing the new dependency.
2. You have at least three options as to how to update `go.mod` to reflect the new dependency:
* Run `go mod tidy -v`. This is a good option if you do not wish to immediately pin to a specific Semantic Version or commit.
* Run, for example, `go get <package-name>@<commit-hash>`. This is a good option when you want to immediately pin to a specific Semantic Version or commit.
* Manually update `go.mod`. If one of the two options above doesn't suit you, do this -- but very carefully.
3. Create a git commit to reflect your code (not vendor) changes. See below for tips on composing commits.
4. Once `go.mod` describes the desired state and you've create a commit for that change, run `make revendor` to update `go.mod`, `go.sum` and `vendor`. This calls `go mod tidy -v`, `go mod vendor -v` and `go mod verify`.
5. Create a git commit to reflect the changes made by `make revendor`. Again, see below for tips on composing commits.
Tests will fail if transitive dependencies aren't included.
Once `glide.yaml` describes the desired state use `make` to update `glide.lock` and `vendor`. This calls both `glide` and `glide-vc` with the set of flags that dex requires.
```
make revendor
```
## Composing commits
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.
@ -30,6 +36,7 @@ connector/ldap: add a LDAP connector
vendor: revendor
```
[glide]: https://github.com/Masterminds/glide
[glide-vc]: https://github.com/sgotti/glide-vc
[go-modules]: https://github.com/golang/go/wiki/Modules
[go-modules-activate]: https://github.com/golang/go/wiki/Modules#how-to-install-and-activate-module-support
[go-vendor]: https://golang.org/cmd/go/#hdr-Vendor_Directories
[module-aware-go-get]: https://tip.golang.org/cmd/go/#hdr-Module_aware_go_get