docs: Done with next stage of ensure docs

Author: sdboyer

docs/FAQ.md

@@ -1,5 +1,9 @@
---
+---
 id: faq.md
+---
+
+
+
 title: FAQ
 --
 
@@ -289,7 +293,7 @@ There's another major performance issue that's much harder - the process of pick
 ## How does `dep` handle symbolic links?
 
 > because we're not crazy people who delight in inviting chaos into our lives, we need to work within one `GOPATH` at a time.
--[@sdboyer in #247](https://github.com/golang/dep/pull/247#issuecomment-284181879)
+> -[@sdboyer in #247](https://github.com/golang/dep/pull/247#issuecomment-284181879)
 
 Out of convenience, one might create a symlink to a directory within their `GOPATH/src`, e.g. `ln -s ~/go/src/github.com/user/awesome-project ~/Code/awesome-project`.
 

docs/day-to-day-dep.md

@@ -2,17 +2,20 @@
 title: Day-to-day dep
 ---
 
-In keeping with Go's philosophy of minimizing knobs, dep has a sparse interface: there are only two commands you're likely to run regularly. `dep ensure` is the primary workhorse command, and after the initial `dep init`, is the only thing you'll run that actually changes disk state. `dep status` is a read-only command that can help you understand the current state of your project. 
+In keeping with Go's philosophy of minimizing knobs, dep has a sparse interface; there are only two commands you're likely to run regularly:
 
-This guide primarily centers on  `dep ensure`, as that's the command you run to effect changes on your project. The [ensure mechanics](ensure-mechanics.md) document details how the command actually works, and is worth reading if you're encountering a confusing `dep ensure` behavior (or just curious!). This guide is more of a high-level tour for folks trying to get a handle on the basics of dep.
+* `dep ensure` is the primary workhorse command, and is the only command that changes disk state.
+* `dep status` reports on the state of your project, and the universe of Go dependencies.
+
+This guide primarily centers on  `dep ensure`, as that's the command you run to effect changes on your project. The [ensure mechanics](ensure-mechanics.md) reference details how the command actually works, and is worth reading if you're encountering a confusing `dep ensure` behavior (or just curious!). This guide is more of a high-level tour for folks trying to get a basic handle on using dep effectively.
 
 ## Basics
 
-Let's start with some semantics: the verb is "ensure" to emphasize that the action being taken is not only performing a single, discrete action (like adding a dependency), but rather enforcing a kind of broader guarantee. Expressing that guarantee In narrative terms, running `dep ensure` is like saying:
+Let's start with some semantics: the verb is "ensure" to emphasize that the action being taken is not only performing a single, discrete action (like adding a dependency), but rather enforcing a kind of broader guarantee. To put that guarantee in narrative terms, running `dep ensure` is like saying:
 
 > Hey dep, please make sure that my project is [in sync](glossary.md#sync): that `Gopkg.lock` satisfies all the imports in my project, and all the rules in `Gopkg.toml`, and that `vendor/` contains exactly what `Gopkg.lock` says it should."
 
-As the narrative indicates, `dep ensure` is a holistic operation; rather than offering a series of commands that you run in succession to incrementally achieve a some final state, each run of `dep ensure` delivers a complete, consistent final state with respect to the inputs of your project. You might think of this like a frog, hopping from lilypad to lilypad: `dep ensure` moves your project from one safe (transitively complete import graph, with all constraints satisfied, and a fully populated `vendor`) island to the the next, or it doesn't move at all. Barring critical, unknown bugs, there are no intermediate failure states. This makes `dep ensure` fine to run at most any time, as it will always drive towards a safe, known good state. 
+As the narrative indicates, `dep ensure` is a holistic operation; rather than offering a series of commands that you run in succession to incrementally achieve a some final state, each run of `dep ensure` delivers a complete, consistent final state with respect to the inputs of your project. It's a bit like a frog, hopping from lilypad to lilypad: `dep ensure` moves your project from one safe (transitively complete import graph, with all constraints satisfied, and a fully populated `vendor`) island to the the next, or it doesn't move at all. There are no known intermediate failure states. This makes `dep ensure` fine to run at most any time, as it will always drive towards a safe, known good state.
 
 General guidelines for using dep:
 
@@ -23,25 +26,26 @@ General guidelines for using dep:
 
 ## Using `dep ensure`
 
-There are five basic times when you'll run `dep ensure` (with and without flags):
+There are four times when you'll run `dep ensure`:
 
 - We want to add a new dependency
-- We want to upgdate an existing dependency
+- We want to update an existing dependency
 - We've imported a package for the first time, or removed the last import of a package
 - We've made a change to a rule in `Gopkg.toml`
-- We're not quite sure if one of the above has happened
 
-Let's explore each of these. To play along at home, you'll need to `cd` into a project that's already managed by dep (by `dep init` - there are separate guides for [new projects](new-project.md) and [migrations](migrating.md)).
+There's also an implicit fifth time: when you're not sure if one of the above has happened. Running `dep ensure` without any additional flags will get your project back in sync - a known good state. As such, it's generally safe to defensively run `dep ensure`  as a way of simply making sure that your project is in that state.
+
+Let's explore each of moments. To play along, you'll need to `cd` into a project that's already been set up by `dep init`. If you haven't done that yet, check out the guides for [new projects](new-project.md) and [migrations](migrating.md).
 
 ### Adding a new dependency
 
-Let's say that we want to introduce a new dependency on  `github.com/pkg/errors`. We can accomplish this with one command:
+Let's say that we want to introduce a new dependency on  `github.com/pkg/errors`. This can be accomplished with one command:
 
 ```
 $ dep ensure -add github.com/pkg/errors
 ```
 
-_Much like git, `dep status` and `dep ensure` can also be run from any subdirectory of your project root, which is determined by the presence of a `Gopkg.toml` file._
+> Much like git, `dep status` and `dep ensure` can also be run from any subdirectory of your project root, which is determined by the presence of a `Gopkg.toml` file.
 
 This should succeed, resulting in an updated `Gopkg.lock` and `vendor/` directory, as well as injecting a best-guess version constraint for `github.com/pkg/errors` into our `Gopkg.toml`. But, it will also report a warning:
 
@@ -50,15 +54,15 @@ This should succeed, resulting in an updated `Gopkg.lock` and `vendor/` director
 If you run "dep ensure" again before actually importing it, it will disappear from Gopkg.lock and vendor/.
 ```
 
-As the warning suggests, you should introduce an `import "github.com/pkg/errors"` in your code, ideally right away. If you don't, a later `dep ensure` run will interpret your newly-added dependency as unused, and automatically get rid of it.
+As the warning suggests, you should introduce an `import "github.com/pkg/errors"` in your code, the sooner the better. If you don't, a later `dep ensure` run will interpret your newly-added dependency as unused, and automatically remove it from `Gopkg.lock` and `vendor/`. This is because, in contrast to other dependency management tools that rely on a metadata file to indicate which dependencies are required, dep considers the import statements it discovers through static analysis of your project's code to be the canonical indicator of what dependencies must be present.
 
-Note that it is not _required_ to use `dep ensure -add` to add new dependencies - you can also just add an appropriate `import` statement in your code, then run `dep ensure`. This approach doesn't always play nicely with  [`goimports`](https://godoc.org/golang.org/x/tools/cmd/goimports), and also won't append a `[[constraint]]` into `Gopkg.toml`. Still, it can be useful at times, often for rapid iteration and off-the-cuff experimenting.
+Note that you do not _have to_ use `dep ensure -add` to add new dependencies - you can also just add an appropriate `import` statement in your code, then run `dep ensure`. This approach doesn't always play nicely with  [`goimports`](https://godoc.org/golang.org/x/tools/cmd/goimports), and also won't append a `[[constraint]]` into `Gopkg.toml`. Still, it can be useful at times, often for rapid iteration and off-the-cuff experimenting.
 
 The [ensure mechanics section on `-add`](ensure-mechanics.md#add) has more detail on internals, as well as some subtle variations in `dep ensure -add`'s behavior.
 
 ### Updating dependencies
 
-Ideally, updating a dependency to a newer version is a single command:
+Ideally, updating a dependency project to a newer version is a single command:
 
 ```
 $ dep ensure -update github.com/foo/bar
@@ -70,11 +74,24 @@ This also works without arguments to try to update all dependencies, though it's
 $ dep ensure -update
 ```
 
-The behavior of `dep ensure -update` is heavily dependent on [the type of constraints in use](ensure-mechanics.md#update-and-constraint-types). For semver range and branch cases, the above CLI-driven approach works. For other types - non-semver releases and revisions (e.g. git hashes) - the only option to achieve an analogous "update" is to manually update `Gopkg.toml` with a new constraints, then run `dep ensure`.
+`dep ensure -update` searches for versions that work with the `branch`, `version`, or `revision` constraint defined in `Gopkg.toml`. These constraint types have different semantics, some of which allow `dep ensure -update` to effectively find a "newer" version, while others will necessitate hand-updating the `Gopkg.toml`. The [ensure mechanics](ensure-mechanics.md#update-and-constraint-types) guide explains this in greater detail, but if you want to know what effect a `dep ensure -update` is likely to have for a particular project, the `LATEST` field in `dep status` output will tell you.
+
+### 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.
+
+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:
 
-### Adding and removing package imports
+1. You've added the first `import` of a package, but already `import` other packages from that project.
+2. You've removed the last `import` of a package, but still `import` other packages from that project.
+3. You've added the first `import` of any package within a particular project. (Note: this is the [alternate adding approach](#adding-a-new-dependency))
+4. You've removed the last `import` of a package from within a particular project.
 
-As described in the 
+In short, dep is concerned with the set of unique import paths across your entire project, and only cares when you make a change that adds or removes an import path from that set.
+
+Of course, especially on large projects, it can be tough to keep track of whether adding or removing (especially removing) a particular import statement actually does change the overall set. Fortunately, you needn't keep close track, as you can run `dep ensure` and it will automatically pick up any additions or removals, and bring your project back in sync.
+
+Only if it is the first/last import of a project being added/removed - cases 3 and 4 - are additional steps needed: `Gopkg.toml` should be updated to add/remove the corresponding project's `[[constraint]]`.
 
 ### Rule changes in `Gopkg.toml`
 
@@ -86,10 +103,6 @@ As described in the
 * `[[override]]`, stanzas identical to `[[constraint]]` except that only the current project can express them and they supersede `[[constraint]]` in both the current project and dependencies
 * `[prune]`, global and per-project rules that govern what kinds of files should be removed from `vendor/`
 
-Changes to any one of these rules will likely necessitate changes in `Gopkg.lock` and `vendor/`; a single successful `dep ensure` run will effect all such changes at once, bringing your project back in sync.
-
-### Or, just, any time
-
-So, you're humming along, working on a project, and 
+Changes to any one of these rules will likely necessitate changes in `Gopkg.lock` and `vendor/`; a single successful `dep ensure` run will incorporate all such changes at once, bringing your project back in sync.
 
 

docs/ensure-mechanics.md

@@ -151,7 +151,7 @@ Ordinarily, when the solver encounters a project name for which there's an entry
 
 If `-update` is passed with no arguments, then `ChangeAll` is set to `true`, resulting in the solver ignoring `Gopkg.lock` for all newly-encountered project names. This is equivalent to explicitly passing all of your dependences as arguments to `dep ensure -update`, as well as `rm Gopkg.lock && dep ensure`. Again, however, neither of these approaches are recommended, and future changes may introduce subtle differences.
 
-When a version hint from `Gopkg.lock` is not placed at the head of the version queue, it means that dep will explore the set of possible versions for a particular dependency. This exploration is performed according to a [fixed sort order](https://godoc.org/github.com/golang/dep/gps#SortForUpgrade), where newer versions are tried first, resulting in an update. 
+When a version hint from `Gopkg.lock` is not placed at the head of the version queue, it means that dep will explore the set of possible versions for a particular dependency. This exploration is performed according to a [fixed sort order](https://godoc.org/github.com/golang/dep/gps#SortForUpgrade), where newer versions are tried first, resulting in an update.
 
 For example, say there is a project, `github.com/foo/bar`, with the following versions:
 
@@ -175,7 +175,7 @@ So, barring some other conflict, `v1.2.0` is selected, resulting in the desired
 
 ### `-update` and constraint types
 
-Continuing with our example, it's important to note that updates with `-update` are achieved incidentally - the solver never explicitly targets a newer version by the solver. It just removes the hint from the lock, then selects the first version in the queue that satisfies constraints. Consequently, `-update` is only effective with certain types of constraints.
+Continuing with our example, it's important to note that updates with `-update` are achieved incidentally - the solver never explicitly targets a newer version. It just skips adding a hint from the lock, then selects the first version in the queue that satisfies constraints. Consequently, `-update` is only effective with certain types of constraints.
 
 It does work with branch constraints, which we can observe by including the underlying revision. If the user has constrained on `branch = "master"`, and `Gopkg.lock` points at an older revision (say, `aabbccd`) than the canonical source's `master` branch points to (`bbccdde`), then `dep ensure` will end up contructing a queue that looks like this:
 
@@ -199,7 +199,7 @@ The key takeaway here is that `-update`'s behavior is governed by the type of co
 | ------------------------------------ | ------------------ | ---------------------------------------- |
 | `version` (semver range)             | `"^1.0.0"`         | Tries to get the latest version allowed by the range |
 | `branch`                             | `"master"`         | Tries to move to the current tip of the named branch |
-| `version` (non-range semver)         | `"=1.0.0"`         | Change can only occur if the upstream release was moved |
+| `version` (non-range semver)         | `"=1.0.0"`         | Change can only occur if the upstream release was moved (e.g. `git push --force <tag>`) |
 | `version` (non-semver)               | `"foo"`            | Change can only occur if the upstream release was moved |
 | `revision`                           | `aabbccd...`       | No change is possible                    |
 | (none)                               | (none)             | The first version that works, according to [the sort order](https://godoc.org/github.com/golang/dep/gps#SortForUpgrade) (not recommended) |

docs/introduction.md

@@ -6,4 +6,4 @@ title: Getting Started
 
 Welcome! This is documentation for dep, the "official experiment" dependency management tool for the Go language. dep is a tool intended primarily for use by developers, to support the work of actually writing and shipping code. It is not intended for end users who are installing Go software - that's what go get does.
 
-This documentation contains both guides and reference material. The guides are practical explanations of how to actually do things with dep, whereas the reference material provides deeper dives on specific topics.  Of particular note is the glossary - if you're unfamiliar with terminology used in this documentation, make sure to check there!
+This documentation contains both guides and reference material. The guides are practical explanations of how to actually do things with dep, whereas the reference material provides deeper dives on specific topics.  Of particular note is the [glossary](#glossary.md) - if you're unfamiliar with terminology used in this documentation, make sure to check there!