documentation improvements for new users #819

afeld · 2017-07-15T18:37:06Z

Hello from Gophercon! I'm a new Dep user/contributor, so decided to work on the first-run experience in terms of documentation.

What does this do / why do we need it?

See the commit messages for details (I tried to keep each one small/discrete), but the high-level overview is:

Moved the FAQ under the docs/ folder, to have one less file at the top level
- This could probably be done with other files, but I didn't want to get too carried away.
Split and expand the Usage information into initial setup and day-to-day interactions with Dep
Don't encourage adding/changing of dependencies through the CLI directly
Minor formatting fixes

What should your reviewer look out for in this PR?

Whether the updated instructions are still recommended/accurate.

Do you need help or clarification on anything?

I don't think so, but I don't know what I don't know.

Which issue(s) does this PR fix?

None.

googlebot · 2017-07-15T18:37:10Z

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://cla.developers.google.com/ to sign.

Once you've signed, please reply here (e.g. I signed it!) and we'll verify. Thanks.

If you've already signed a CLA, it's possible we don't have your GitHub username or you're using a different email address. Check your existing CLA data and verify that your email is set on your git commits.
If your company signed a CLA, they designated a Point of Contact who decides which employees are authorized to participate. You may need to contact the Point of Contact for your company and ask to be added to the group of authorized contributors. If you don't know who your Point of Contact is, direct the project maintainer to go/cla#troubleshoot.
In order to pass this check, please resolve this problem and have the pull request author add another comment and the bot will run again.

afeld · 2017-07-15T18:55:11Z

I'm a federal employee, so getting the CLA signed may not be quick 😕 Working it up the chain, but would love feedback in the meantime.

afeld · 2017-07-15T20:02:09Z

README.md

 Get the tool via

 ```sh
 $ go get -u github.com/golang/dep/cmd/dep
 ```

-Typical usage on a new repo might be
+To set up Dep on a project, run the following from your project root directory:


Perhaps this is an over-simplification? /cc #731

We use dep instead of "Dep".

"To start managing dependencies using dep, ..."?

I don't know, but I still think we can come up with something better here. 😁

ibrasho · 2017-07-15T20:55:17Z

README.md


 ```sh
 $ dep init
 $ dep ensure -update
 ```

+If your project was already using a `vendor/` directory, it was backed up to `_vendor-TIMESTAMP/`.


"If a vendor/ directory existed in your project root, it should have been backed up to _vendor-TIMESTAMP/."?

I'm not sure, but I think this one could use some rephrasing.

ibrasho · 2017-07-15T20:56:43Z

docs/FAQ.md

@@ -24,7 +24,6 @@ Summarize the question and quote the reply, linking back to the original comment
 * [Why did `dep` use a different revision for package X instead of the revision in the lock file?](#why-did-dep-use-a-different-revision-for-package-x-instead-of-the-revision-in-the-lock-file)
 * [Why is `dep` slow?](#why-is-dep-slow)
 * [How does `dep` handle symbolic links?](#how-does-dep-handle-symbolic-links)
-* [`dep` deleted my files in the vendor directory!](#dep-deleted-my-files-in-the-vendor-directory)


Why did you remove this question?

I removed the section it links to, because that information is now in the README.

ibrasho · 2017-07-15T20:59:06Z

README.md

 Get the tool via

 ```sh
 $ go get -u github.com/golang/dep/cmd/dep
 ```

-Typical usage on a new repo might be
+To set up Dep on a project, run the following from your project root directory:


We use dep instead of "Dep".

ibrasho · 2017-07-15T21:03:45Z

README.md

 Get the tool via

 ```sh
 $ go get -u github.com/golang/dep/cmd/dep
 ```

-Typical usage on a new repo might be
+To set up Dep on a project, run the following from your project root directory:


"To start managing dependencies using dep, ..."?

I don't know, but I still think we can come up with something better here. 😁

afeld · 2017-07-15T22:25:43Z

@carolynvs Went ahead and added some of the things we talked about in person. Thanks for the help!

sdboyer

these are generally fantastic changes - really feel like they're taking the docs in the right direction!

just a few notes. hopefully you'll get through that CLA soon 😄

sdboyer · 2017-07-18T03:00:19Z

README.md

+## Usage
+
+There is one main subcommand you will use: `dep ensure`. `ensure` synchronizes
+your dependencies in `vendor/` to make sure they match what's in your `import`s


Close, but a little off the mark. Maybe:

ensure first makes sure Gopkg.lock is consistent with your imports and Gopkg.toml, and then that vendor has is poopulated with exactly what's described in Gopkg.lock.

sdboyer · 2017-07-18T03:01:12Z

README.md

+(if your `vendor/` directory isn't [checked in with your code](](docs/FAQ.md#should-i-commit-my-vendor-directory)))
+
+```sh
+$ dep ensure


can we stick TODOs in these files without them showing up in normal reading mode? If so, we should link to #489, as it may change what we tell people here a bit.

Done. Might want to add a TODO in that pull request, as well.

sdboyer · 2017-07-18T03:06:19Z

README.md

+
+1. Remove from `Gopkg.toml`, if it was in there.
+
+### Testing changes to a dependency


This simple advice will work for quickly testing local changes, but not for actually keeping any of them in Gopkg.lock or vendor in any kind of portable way. It's probably worth noting that, as well as that we may not have a really good solution for this until after toolchain integration (see gist)

It may be worth linking to virtualgo, as well, as it offers one interim attempt at a solution.

sdboyer · 2017-07-18T03:08:46Z

@afeld oh, also - there's no way for you to sign the CLA as an individual?

carolynvs

I ❤️ IT! One million pony points for giving the doc, and therefore our users, some much needed love.

carolynvs · 2017-07-18T22:02:51Z

README.md


 Get the tool via

 ```sh
 $ go get -u github.com/golang/dep/cmd/dep
 ```

-Typical usage on a new repo might be
+To start managing dependencies using dep, run the following from your project root directory:

 ```sh
 $ dep init
 $ dep ensure -update


Now that the instructions above have changed from "here are typical commands" to "Do this to start using dep", we should remove dep ensure -update.

All you need to start using dep is init, and if they had specific versions identified by dep either from their GOPATH, or other dependency managers, we don't want to immediately clobber them. 😀

carolynvs · 2017-07-18T22:04:55Z

README.md


 ```sh
 $ dep init
 $ dep ensure -update
 ```

-To update a dependency to a new version, you might run
+`dep init` will do the following:


Suggestion: change to "This does the following".

carolynvs · 2017-07-18T22:10:42Z

README.md

+### Adding a dependency
+
+1. Add the `import` in your source code file(s).
+1. Download via dep.


Maybe change this to

Run the following command to update your Gopkg.lock and populate `vendor/` with the new dependency.

carolynvs · 2017-07-18T22:14:08Z

README.md

+
+### Checking the status of dependencies
+
+```sh


status will also tell you when your lock file is out of date, which can happen when you've added imports, or edited the manifest, but have not yet rerun dep ensure. Let's show an example of that output and let people know the way to "fix" it is to run dep ensure again.

Mind if we take care of that as a follow-up?

Yup! That's fine.

carolynvs · 2017-07-18T22:15:24Z

README.md

+dependency into `vendor/` based on your manifest, as if you were installing from
+scratch.
+
+To test out code that is pushed, see [changing dependencies](#changing-dependencies).


"To test out code that has been pushed to a new version, branch or fork"

carolynvs

🎉

afeld · 2017-07-19T02:45:36Z

Realizing that, while I was at Gophercon in my official capacity, I made these contributions as myself. Signed the contributor agreement as an individual, and rebased the commits to use my personal instead of work email. Hopefully we'll get the CLA signed as an organization so contributions can happen more seamlessly in the future. Good to go!

googlebot · 2017-07-19T02:45:40Z

CLAs look good, thanks!

ibrasho

Minor nits. No showstoppers though. 👍

ibrasho · 2017-07-19T17:40:38Z

README.md


 Get the tool via

 ```sh
 $ go get -u github.com/golang/dep/cmd/dep
 ```

-Typical usage on a new repo might be
+To start managing dependencies using dep, run the following from your project root directory:


~~dep with backticks.~~ 😁

ibrasho · 2017-07-19T17:42:13Z

README.md

+This does the following:
+
+1. Look for [existing dependency management files](docs/FAQ.md#what-external-tools-are-supported) to convert
+1. Check if your dependencies use dep


~~dep with backticks.~~

I don't want to sidetrack/bikeshed this issue (so we can continue discussing in a new issue if necessary), but would ask that we don't backtick every mention of dep. 😀

One easy way to think about it this: only use backticks if we are telling them to run a command, referring to a dep command, etc. Anytime we are simply referring to the dep project, leave off the special formatting.

Examples:

Check if your dependencies use dep...

Run dep ensure to populate the vendor directory...

We recommend using dep in your Makefiles...

Verify that dep is on your $PATH...

I would argue that we are almost always referring to dep as the binary (or CLI tool) in the docs. But I'm okay with that anyway. 😁

ibrasho · 2017-07-19T17:45:10Z

README.md

+
+### Adding a dependency
+
+1. Add the `import` in your source code file(s).


Maybe: "import the package in your *.go source code file(s)."?

ibrasho · 2017-07-19T17:49:32Z

README.md

+
+### Testing changes to a dependency
+
+Making changes in your `vendor/` directory directly is not recommended, as dep


~~dep with backticks.~~ 😁

ibrasho · 2017-07-19T17:50:37Z

README.md

+dependency into `vendor/` based on your manifest, as if you were installing from
+scratch.
+
+This solution works for short-term use, but for something longer-term, take a


"long-term"

carolynvs · 2017-07-20T16:45:11Z

@afeld I would love to merge this but some recent commits conflict with this PR. Let me know if you'd like to resolve them yourself, or I can do that for you. Happy to help either way.

The top-level directory is getting a bit cluttered, so group the FAQ alongside the other documentation. Also did some minor formatting cleanup of that file.

- Clarified that the Usage commands in the README apply to both new and existing projects - Move information about the vendor directory backup into the README. This gives the user the necessary context as soon as they would need it, rather than needing to stumble upon it (somewhat buried) in the FAQ.

- Explain that `dep init` will try and import from other package managers - Explain the day-to-day workflow of using Dep.

The former seems to be falling out of favor, and may confuse users about which is preferable to use.

Trying to match the different common use cases a user will have for interacting with dep.

@carolynvs

…o dependencies ...to the README. Also, expanded on the description of what `dep init` does. All of this was taken from @carolynvs's lightning talk on dep. http://carolynvs.com/dep-in-10

Switched to `Setup` and `Usage` instead of `Initial setup` and `Day-to-day workflows`. Also made both of those top-level section headings, so that the various workflows aren't nested so deeply.

My hypothesis is that these explanations will be more useful as users are reading about the sections themselves, rather than low down in the FAQ, where they could easily be missed.

afeld · 2017-07-21T01:17:25Z

Rebased, and took care of the new suggestions.

carolynvs · 2017-07-21T14:43:15Z

README.md


 ```sh
-$ dep ensure github.com/pkg/errors@^0.8.0
+$ dep ensure -update


One more follow-up issue (I'll create after this is merged) is to cover how to update a single package, and how to pick the version/revision.

carolynvs · 2017-07-21T14:49:57Z

README.md

+
+There is one main subcommand you will use: `dep ensure`. `ensure` first makes
+sure `Gopkg.lock` is consistent with your `import`s and `Gopkg.toml`, and then
+that `vendor/` is populated with exactly what's described in `Gopkg.lock`. `dep


Sorry to add something at the last minute but someone was just tripped up by this definition of dep ensure yesterday. #865 (comment)

`ensure` first makes sure `Gopkg.lock` is consistent with your `import`s and `Gopkg.toml`. Then if any changes are detected, populates `vendor/` with exactly what's described in `Gopkg.lock`.

We don't validate that the vendor directory matches the lock currently, and hopefully this will make that more clear! 😀

carolynvs · 2017-07-21T21:22:42Z

YOU ARE AWESOME! 🎉 Thanks for the much needed documentation.

carolynvs · 2017-07-21T21:34:20Z

I've gone ahead and added follow-up issues #876 and #877.

googlebot added the cla: no label Jul 15, 2017

afeld force-pushed the docs-improvements branch from 91c1d5d to 2eca4b3 Compare July 15, 2017 19:58

afeld commented Jul 15, 2017

View reviewed changes

ibrasho reviewed Jul 15, 2017

View reviewed changes

afeld force-pushed the docs-improvements branch from c656272 to 8c66b03 Compare July 15, 2017 22:02

sdboyer suggested changes Jul 18, 2017

View reviewed changes

carolynvs suggested changes Jul 18, 2017

View reviewed changes

carolynvs approved these changes Jul 19, 2017

View reviewed changes

afeld force-pushed the docs-improvements branch from cb941f9 to 5c3adec Compare July 19, 2017 02:41

googlebot added cla: yes and removed cla: no labels Jul 19, 2017

ibrasho reviewed Jul 19, 2017

View reviewed changes

afeld added 9 commits July 20, 2017 21:09

Move the FAQ under the docs/ folder

2bdcdd8

The top-level directory is getting a bit cluttered, so group the FAQ alongside the other documentation. Also did some minor formatting cleanup of that file.

Explain first-run vs. day-to-day workflow

8f94e29

- Explain that `dep init` will try and import from other package managers - Explain the day-to-day workflow of using Dep.

Direct users to modify dependencies via files rather than CLI commands

b023c29

The former seems to be falling out of favor, and may confuse users about which is preferable to use.

Change introductory wording

3a6df18

Split apart the day-to-day workflows

f0b8c47

Trying to match the different common use cases a user will have for interacting with dep.

Add workflows around checking status, removing, and testing changes t…

7b1aaa6

…o dependencies ...to the README. Also, expanded on the description of what `dep init` does. All of this was taken from @carolynvs's lightning talk on dep. http://carolynvs.com/dep-in-10

Rename README headings to match common terminology

97f5c61

Switched to `Setup` and `Usage` instead of `Initial setup` and `Day-to-day workflows`. Also made both of those top-level section headings, so that the various workflows aren't nested so deeply.

Put plain language definitions of manifest sections in context

facfb6e

My hypothesis is that these explanations will be more useful as users are reading about the sections themselves, rather than low down in the FAQ, where they could easily be missed.

afeld force-pushed the docs-improvements branch from 5c3adec to 53546d9 Compare July 21, 2017 01:16

carolynvs reviewed Jul 21, 2017

View reviewed changes

carolynvs suggested changes Jul 21, 2017

View reviewed changes

afeld force-pushed the docs-improvements branch from 53546d9 to e7d91f6 Compare July 21, 2017 16:13

README updates based on feedback

e7d91f6

carolynvs mentioned this pull request Jul 21, 2017

Document the prune command #875

Closed

carolynvs approved these changes Jul 21, 2017

View reviewed changes

carolynvs merged commit bcfa7ee into golang:master Jul 21, 2017

carolynvs mentioned this pull request Jul 21, 2017

Document status's lock mismatch state #876

Closed


		1. Remove from `Gopkg.toml`, if it was in there.

		### Testing changes to a dependency


		### Adding a dependency

		1. Add the `import` in your source code file(s).


		### Testing changes to a dependency

		Making changes in your `vendor/` directory directly is not recommended, as dep

documentation improvements for new users #819

documentation improvements for new users #819

Conversation

afeld commented Jul 15, 2017

What does this do / why do we need it?

What should your reviewer look out for in this PR?

Do you need help or clarification on anything?

Which issue(s) does this PR fix?

googlebot commented Jul 15, 2017

afeld commented Jul 15, 2017

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

afeld commented Jul 15, 2017

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

sdboyer commented Jul 18, 2017

carolynvs 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

carolynvs left a comment

Choose a reason for hiding this comment

afeld commented Jul 19, 2017

googlebot commented Jul 19, 2017

ibrasho left a comment

Choose a reason for hiding this comment

ibrasho Jul 19, 2017 • edited Loading

Choose a reason for hiding this comment

ibrasho Jul 19, 2017 • edited Loading

Choose a reason for hiding this comment

carolynvs Jul 19, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ibrasho Jul 19, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

carolynvs commented Jul 20, 2017

afeld commented Jul 21, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

carolynvs commented Jul 21, 2017

carolynvs commented Jul 21, 2017 • edited Loading

ibrasho Jul 19, 2017 •

edited

Loading

ibrasho Jul 19, 2017 •

edited

Loading

carolynvs Jul 19, 2017 •

edited

Loading

ibrasho Jul 19, 2017 •

edited

Loading

carolynvs commented Jul 21, 2017 •

edited

Loading