Add a FAQ #401

carolynvs · 2017-04-19T19:04:20Z

This gives us a place to collect great questions and their helpful answers in one place until #331 is hammered out.

I went through all the issues labeled with doc and quoted like the wind to get it jump started.

Here are the issues that I think are resolved with this PR, because they were kept open in order to get the question documented:

sdboyer

this is a great start 😄

sdboyer · 2017-04-20T00:00:33Z

FAQ.md

+    Constraints given in a project's manifest are only applied if the
+    dependent project is actually imported. Transitive dependencies (dependencies
+    of your imports) are only updated when the revision in the lockfile no
+    longer meets the constraints of your direct dependencies.


Ah, I think you've flipped the idea from #385 around a bit. While you can only constrain a direct dependency, you can (or at least should be able to) mark any dependency, transitive or direct, for updating.

Sorry I don't quite understand what you mean by "you can (or at least should be able to) mark any dependency, transitive or direct, for updating". Can you help me identity which line(s) are missing the mark? 😊

I thought that problem from #385 (and #302 come to think of it) was that because X was not a direct dependency (not imported), running dep ensure -update did not cause X to be updated, even though X is a dependency in the manifest? So the resolution is either:

Be okay with it not being updated during dep ensure -update unless forced by the constraints of your direct dependencies.

Make X as an override or required package in the manifest.

Though the best solution is to fix #302 and when dep detects this situation, it stops and prints a message to the user on how to fix it.

You're in the ballpark there, it's just that you've got it sorta reversed. It seems like you're thinking of it as a one-step process (just the dep ensure -update run). But it tends to be more like this:

User puts a constraint on a transitive dependency in manifest, runs dep ensure

dep doesn't point out to user that the constraint is ineffectual, so user assumes it's working (and maybe the constraint they put in the manifest happened to be the one that ended up in the lock).

Later, user runs dep ensure -update, which appears to not have an effect because it was unconstrained on the previous dep ensure, so the latest version is already what was in the lock.

Yes, I agree that fixing #302 is the thing that's most likely to make this better the fastest.

sdboyer · 2017-04-20T00:02:07Z

FAQ.md

+    > However, before taking either of those steps, I'd say it's worth asking if you actually need to use master of github.com/gorilla/context. I imagine it's imported by github.com/gorilla/mux - and if that package is OK with using the tagged release instead of master (which is the preferred mode of operation anyway), then maybe that should be good enough for you? If you really needed something out of github.com/gorilla/context, then you'd probably be importing it directly and doing something with it
+    -[@sdboyer in #385](https://github.com/golang/dep/issues/385#issuecomment-294361087)
+
+* Is package X included in the `ignored` list in your manifest?


If a package is ignored, then it shouldn't be showing up at all in lock or vendor - so there shouldn't be anything to update.

Doh! This wasn't meant to be in here. I thought there may be more scenarios to troubleshoot where you hoped that a package would be updated, and it wasn't. I'll remove this.

sdboyer · 2017-04-20T00:06:43Z

FAQ.md

+-[@sdboyer in #371](https://github.com/golang/dep/issues/371#issuecomment-293246832)
+
+## Does `dep` replace `go get`?
+


Probably would be good to do a bit more caveating here - this is one of the lesser-explored areas with @rsc so far. So, even though the opinions expressed here are tentative, only having them doesn't really paint a representative picture moving forward.

I'll think about some other verbiage...

I'd appreciate any wording you may have for this. Obviously I'm still learning and don't always summarize things right! 😀

Okay I took a stab at being coy and vague about dep and go proper. 😀

sdboyer · 2017-04-20T00:06:56Z

FAQ.md

@@ -0,0 +1,112 @@
+# FAQ
+
+_The first rule of FAQ is don't bikeshed the FAQ, leave that for


sdboyer · 2017-04-20T00:10:06Z

FAQ.md

+> We prefer to treat the use of vendor/ as an implementation detail.
+-[@sdboyer on go package management list](https://groups.google.com/d/msg/go-package-management/et1qFUjrkP4/LQFCHP4WBQAJ)
+
+## Unable to update checked out version: fatal: reference is not a tree


I think this one actually should be fixed now. ...well, arguably not "fixed", as the outcome might not be right - it just silently ignores the commit from on-disk and falls back to the latest version from upstream...but at least, there's no error anymore 😄

We should double check on that before putting this into the FAQ

Oooh yeah you're right. Here is the new behavior #405.

sdboyer · 2017-04-20T00:10:40Z

FAQ.md

+    Remove it from `ignored` and try again.
+
+## Why is `dep` ignoring the version specified in the manifest?
+Only direct dependencies can be managed with a `depenencies` entry


peterbourgon · 2017-04-21T08:41:29Z

Suggestion, since this question comes in very frequently in #vendor:

## Should I commit my vendor directory?

Committing the vendor directory is totally up to you. There is no general advice
that applies in all cases. Pros: it's the only way to get truly reproducible
builds, as it guards against upstream renames and deletes; and you don't need an
extra `dep ensure` step on fresh clones to build your repo. Cons: your repo will
be bigger, potentially a lot bigger; and PR diffs are more annoying.

The behavior has changed, and now instead of a failing, dep picks a new commit.

carolynvs · 2017-04-21T19:30:25Z

Okeedokee!

Taken another crack at explaining why dep ensure -update didn't work as expected. If I am still getting it wrong, I vote for either removing it for now or you giving me the exact verbiage to use in the FAQ for this question. 😀
Added @peterbourgon 's "Should I commit my vendor directory"?
Updated answer to reflect new behavior for "revision is not a tree"
Added caveats to dep vs. go get

sdboyer · 2017-04-25T01:36:30Z

Cool. I'm gonna merge this as it stands now, then push up some more tweaks tonight :)

sdboyer · 2017-04-25T01:36:34Z

thanks!

Add a FAQ

Add a FAQ

c20dddc

googlebot added the cla: yes label Apr 19, 2017

sdboyer suggested changes Apr 20, 2017

View reviewed changes

daenney mentioned this pull request Apr 21, 2017

docs: Create a FAQ #406

Closed

carolynvs added 6 commits April 21, 2017 09:05

FAQ: Should I commit my vendor directory?

1d44331

Fix typo

c41dfce

Update answer for “revision is not a tree”

227404c

The behavior has changed, and now instead of a failing, dep picks a new commit.

Correct answer for why deploy didn’t update a dependency as expected

db0acd4

Add caveats to dep vs. go get answer

15de9b0

Attempt to better explain why -update doesn't work for transitive deps

3617095

carolynvs force-pushed the faq branch from 46f64fa to 3617095 Compare April 21, 2017 19:26

sdboyer approved these changes Apr 25, 2017

View reviewed changes

sdboyer merged commit a28d05c into golang:master Apr 25, 2017

ibrasho pushed a commit to ibrasho-forks/dep that referenced this pull request May 10, 2017

Merge pull request golang#401 from carolynvs/faq

19122dc

Add a FAQ

carolynvs deleted the faq branch June 11, 2017 15:26

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add a FAQ #401

Add a FAQ #401

carolynvs commented Apr 19, 2017 •

edited

Loading

sdboyer left a comment

sdboyer Apr 20, 2017

carolynvs Apr 20, 2017

sdboyer Apr 21, 2017

sdboyer Apr 20, 2017

carolynvs Apr 20, 2017

sdboyer Apr 20, 2017

carolynvs Apr 20, 2017

carolynvs Apr 21, 2017

sdboyer Apr 20, 2017

sdboyer Apr 20, 2017

carolynvs Apr 20, 2017

sdboyer Apr 20, 2017

peterbourgon commented Apr 21, 2017 •

edited

Loading

carolynvs commented Apr 21, 2017

sdboyer commented Apr 25, 2017

sdboyer commented Apr 25, 2017

		-[@sdboyer in #371](https://github.com/golang/dep/issues/371#issuecomment-293246832)

		## Does `dep` replace `go get`?

		@@ -0,0 +1,112 @@
		# FAQ

		_The first rule of FAQ is don't bikeshed the FAQ, leave that for

Add a FAQ #401

Add a FAQ #401

Conversation

carolynvs commented Apr 19, 2017 • edited Loading

sdboyer left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

peterbourgon commented Apr 21, 2017 • edited Loading

carolynvs commented Apr 21, 2017

sdboyer commented Apr 25, 2017

sdboyer commented Apr 25, 2017

carolynvs commented Apr 19, 2017 •

edited

Loading

peterbourgon commented Apr 21, 2017 •

edited

Loading