Skip to content

Commit

Permalink
dep: Update docs to reflect vendor verification
Browse files Browse the repository at this point in the history
  • Loading branch information
sdboyer committed Jul 9, 2018
1 parent 5c8a1e3 commit d7a412f
Show file tree
Hide file tree
Showing 5 changed files with 33 additions and 20 deletions.
41 changes: 30 additions & 11 deletions docs/Gopkg.lock.md

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion docs/daily-dep.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ $ dep ensure -update

### Adding and removing `import` statements

As noted in [the section on adding dependencies](#adding-a-new-dependency), dep relies on the import statements in your code to figure out which dependencies your project actually needs. Thus, when you add or remove import statements, dep might need to care about it.
As noted in [the section on adding dependencies](#adding-a-new-dependency), dep relies on the `import` statements in your code to figure out which dependencies your project actually needs. Thus, when you add or remove import statements, dep might need to care about it.

It's only "might," though, because most of the time, adding or removing imports doesn't matter to dep. Only if one of the following has occurred will a `dep ensure` be necessary to bring the project back in sync:

Expand Down
2 changes: 0 additions & 2 deletions docs/ensure-mechanics.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,9 +51,7 @@ The four state system, and these functional flows through it, are the foundation
One of dep's design goals is that both of its "functions" minimize both the work they do, and the change they induce in their respective results. (Note: "minimize" is not currently formally defined with respect to a cost function.) Consequently, both functions peek ahead at the pre-existing result to understand what work actually needs to be done:

* The solving function checks the existing `Gopkg.lock` to determine if all of its inputs (project import statements + `Gopkg.toml` rules) are satisfied. If they are, the solving function can be bypassed entirely. If not, the solving function proceeds, but attempts to change as few of the selections in `Gopkg.lock` as possible.
* WIP: The current implementation's check relies on a coarse heuristic check that can be wrong in some cases. There is a [plan to fix this](https://github.com/golang/dep/issues/1496).
* The vendoring function hashes each discrete project already in `vendor/` to see if the code present on disk is what `Gopkg.lock` indicates it should be. Only projects that deviate from expectations are written out.
* WIP: the hashing check is generally referred to as "vendor verification," and [is not yet complete](https://github.com/golang/dep/issues/121). Without this verification, dep is blind to whether code in `vendor/` is correct or not; as such, dep must defensively re-write all projects to ensure the state of `vendor/` is correct.

Of course, it's possible that, in peeking ahead, either function might discover that the pre-existing result is already correct - so no work need be done at all. Either way, when each function completes, we can be sure that the output, changed or not, is correct with respect to the inputs. In other words, the inputs and outputs are "in sync." Indeed, being in sync is the "known good state" of dep; `dep ensure` (without flags) guarantees that if it exits 0, all four states in the project are in sync.

Expand Down
6 changes: 1 addition & 5 deletions docs/env-vars.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,4 @@ This is primarily useful if you're not using the standard `go` toolchain as a co

### `DEPNOLOCK`

By default, dep creates an `sm.lock` file at `$DEPCACHEDIR/sm.lock` in order to
prevent multiple dep processes from interacting with the [local
cache](glossary.md#local-cache) simultaneously. Setting this variable will
bypass that protection; no file will be created. This can be useful on certain
filesystems; VirtualBox shares in particular are known to misbehave.
By default, dep creates an `sm.lock` file at `$DEPCACHEDIR/sm.lock` in order to prevent multiple dep processes from interacting with the [local cache](glossary.md#local-cache) simultaneously. Setting this variable will bypass that protection; no file will be created. This can be useful on certain filesystems; VirtualBox shares in particular are known to misbehave.
2 changes: 1 addition & 1 deletion docs/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ An `import` statement that points to a package in a project other than the one i

### GPS

Stands for "Go packaging solver", it is [a subtree of library-style packages within dep](https://godoc.org/github.com/golang/dep/gps), and is the engine around which dep is built. Most commonly referred to as "gps."
Acronym for "Go packaging solver", it is [a subtree of library-style packages within dep](https://godoc.org/github.com/golang/dep/gps), and is the engine around which dep is built. Most commonly referred to as "gps."

### Local cache

Expand Down

0 comments on commit d7a412f

Please sign in to comment.