k-space/dex
Archived
10
0
Fork 0
Code Issues Pull Requests Packages Projects Activity

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

Browse Source 
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
1 changed files with 22 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
Documentation/dev-dependencies.md
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