[WIP] Add a mountain of docs #1499

sdboyer · 2018-01-01T21:09:41Z

What does this do / why do we need it?

This introduces a whole pile of docs for dep, both guides and reference materials. The intent is to also generate a static, versioned site via docusaurus that includes a blog, though i may defer that to a follow-up.

These docs are a WIP. i want to get at least a base set of them done for the v0.4.0 release, but there's going to be plenty still left to write.

TODO for this PR:

Basic coverage of the solver - just enumerate solving failures, then backlink to old gps wiki page
Separate out discussion of failure handling
ensure mechanics reference (still need sync and pkgtree discussion)
Rejigger the whole "day-to-day dep" doc; interlace it with the "ensure mechanics" reference
Gopkg.lock docs
further flesh out deduction section
Make sure all links are hooked up

defer to followup:

~~dep in monorepos~~
~~review FAQ for items that are now better-covered elsewhere~~
~~Retouch Gopkg.toml docs~~
~~Zen of constraints/locks guide~~

What should your reviewer look out for in this PR?

Spelling errors, things that are wrong, things that are glaringly missing

Which issue(s) does this PR fix?

fixes #988
fixes #1054
fixes #1319
fixes #331
fixes #233

bacongobbler · 2018-01-03T18:18:22Z

docs/Gopkg.toml.md


 ## `metadata`
 `metadata` can exist at the root as well as under `constraint` and `override` declarations.

 `metadata` declarations are ignored by dep and are meant for usage by other independent systems.

-A `metadata` declaration at the root defines metadata about the project itself. While a `metadata` declaration under a `constraint` or an `override` defines metadata about that `constraint` or `override`.
+The root `metadata` declaration defines informatino about the project itself, while a `metadata` declaration under a `[[constraint]]` or an `[[override]]` defines metadata about that rule, for the `name`d project.


typo: information

ah, thanks!

jmank88 · 2018-01-03T19:38:36Z

docs/FAQ.md

+--
+id: faq.md
+title: FAQ
+--


Most of these have three dashes, but this one has two and another place has four. Should they all be three?

ah yes, they should, thanks

ibrasho · 2018-01-04T10:26:37Z

docs/Gopkg.toml.md

+* [`constraints`](#constraint) and [`overrides`](#override) allow the user to specify which versions of dependencies are acceptable, and where they should be retrieved from.
+* [`required`](#required) and [`ignored`](#ignored) allow the user to manipulate the import graph by including or excluding import paths, respectively.
+* [`metadata`](#metadata) is a user-defined map of key-value pairs that dep will preserve and ignore.
+


prune settings?

i thought i'd added that in there, hmm, i'll make sure it gets taken care of

ibrasho · 2018-01-04T10:35:11Z

docs/new-project.md

+
+1. A project that is now or eventually may be shared with or imported by other projects/people. In this case, pick the import path corresponding to the VCS root of its intended network location, e.g., `$GOPATH/src/github.com/golang/dep`.
+2. An entirely local project - one that you have no intention of pushing to a central server (like GitHub). In this case, any subdirectory beneath `$GOPATH/src` will do.
+3. A project that needs to live within a large repository, such as a company monorepo. This is possible, but gets more complicated - see [dep in monorepos]().


Is this link missing intentionally?

yeah, there's a bunch of missing links as i go through (note the TODO in the OP)

Now only basic explanations of solving failures are missing. Also includes relevant glossary updates.

Just tidying and deduction left now before the first mountain of docs can be called complete.

jtaekema-stripe · 2018-01-18T22:18:45Z

docs/migrating.md

+
+### Hard failures
+
+Hard failures involve actual 


sentence fragment?

carolynvs

I just have some minor comments that can easily be addressed later.

carolynvs · 2018-01-22T17:14:25Z

docs/Gopkg.toml.md

@@ -156,7 +194,7 @@ codename = "foo"
  name = "github.com/user/project"
  version = "1.0.0"

-  [constraint.metadata]
+  [metadata]


Did this change? I thought we needed the prefix?

carolynvs · 2018-01-22T17:19:51Z

docs/glossary.md

+
+## Override
+
+An override is a [`[[override]]`](Gopkg.toml.md#override) stanza in `Gopkg.toml`. 


It's worth repeating here that overrides only apply to the current project.

carolynvs · 2018-01-22T17:22:16Z

docs/migrating.md

+### The Inference Phase
+
+The inference phase is where `dep init`'s behavior varies. By default, `dep init` will look in your codebase for metadata files from [other Go package management tools that it understands](https://github.com/golang/dep/tree/master/internal/importers), and attempt to automatically migrate the data in these files into concepts that make sense in a dep. Depending on the tool and the particular values dep finds, metadata from the tool may be treated as either:
+


We should clarify that we don't (yet) take into account external config in your dependencies and only import from the current project.

carolynvs · 2018-01-22T17:23:50Z

docs/migrating.md

+
+If you do encounter problems like this, `dep status` is your first diagnostic step; it will report what versions were selected for all your dependencies. It may be clear which dependencies are a problem simply from your building or testing error messages. If not, compare the `dep status` list against the versions recorded by your previous tool to find the differences.
+
+Once you've identified the problematic dependenc(ies), the next step is exerting appropriate controls over them via `Gopkg.toml`. (Note - this advice is intentionally terse; check out [Zen of Dep]() if you want a deeper understanding of how to optimally utilize dep's controls)


Zen of dep is missing a URL

it's also missing a writeup right now :(

carolynvs · 2018-01-22T17:25:44Z

docs/migrating.md

+
+* If the wrong `[[constraint]]` was inferred for one of your direct dependencies, change it. Then, file an issue against dep (please!) - while `dep init` may choose to omit a constraint, converting one incorrectly is considered a bug.
+* If one of your transitive dependencies is at the wrong version, define an `[[override]]` on it to force it to the version you need.
+  * If the version you need is a specific git commit, it's preferable to instead manually change the `revision` to the desired hash in `Gopkg.lock` for that project, then drop the `version` or `branch` fields (if any).


This directly conflicts with statement further up that says that if you end up manually editing Gopkg.lock, open a feature/bug. I always end up manually modifying both files after init to get things just right, so maybe that statement should be softened.

Gopkg.lock is strictly autogenerated; editing it manually is an antipattern. If there is a goal you can only achieve by hand-editing Gopkg.lock, it is at least a feature request, and likely a bug.

modified, thanks

carolynvs · 2018-01-22T17:28:19Z

docs/migrating.md

+* If one of your transitive dependencies is at the wrong version, define an `[[override]]` on it to force it to the version you need.
+  * If the version you need is a specific git commit, it's preferable to instead manually change the `revision` to the desired hash in `Gopkg.lock` for that project, then drop the `version` or `branch` fields (if any).
+* If one of your direct dependencies is at the wrong version and there's no `[[constraint]]` on it in `Gopkg.toml` already, then define an appropriate one.
+  * As with the transitive dependencies, if the version you need is a specific git commit, prefer doing that manually in `Gopkg.lock`.


We don't need to address this in this PR, but the advice for libraries on how to deal with transitive dependencies is something that could really use some beefing up. People are very unclear on root, vs current when it comes to libraries, when overrides will work, how to trick dep into doing the right thing, etc. Of course if we merge my PR (#1489), it would be simpler.

yeah, gonna need to defer to followup

Assorted edits and wording tweaks, as well as including bash as type on most of the fenced code blocks. Also relocated assets into docs/assets from docs/img in order to accommodate docusaurus' expected layout.

This was nominally to incorporate prune docs, but it became a broader rewrite that was really needed, anyway.

Closes #1499.

sdboyer added the docs label Jan 1, 2018

sdboyer added this to the v0.4.0 milestone Jan 1, 2018

googlebot added the cla: yes label Jan 1, 2018

bacongobbler reviewed Jan 3, 2018

View reviewed changes

jmank88 reviewed Jan 3, 2018

View reviewed changes

ibrasho reviewed Jan 5, 2018

View reviewed changes

sdboyer mentioned this pull request Jan 6, 2018

dep init fails if in not in $GOPATH[...]/src/{somedir..} #148

Closed

carolynvs mentioned this pull request Jan 8, 2018

[WIP] Prototype doc site #1369

Closed

5 tasks

sdboyer mentioned this pull request Jan 9, 2018

Absorb prune into ensure #944

Closed

1 task

sdboyer added 8 commits January 17, 2018 00:33

docs: incremental checkin of numerous new docs

af75280

docs: Incremental checkin, mostly ensure mechanics

d047b58

docs: Done with next stage of ensure docs

bb08cee

docs: Add solver and failures doc; misc others

b2c090f

docs: Failure modes doc nearly done.

7f60cb3

Now only basic explanations of solving failures are missing. Also includes relevant glossary updates.

docs: Add Gopkg.lock.md

adb9a56

docs: Penultimate docs changeset

afb1cd6

Just tidying and deduction left now before the first mountain of docs can be called complete.

docs: Fix up README, polish deduction and intro

7ae1fda

sdboyer force-pushed the docusaurus branch from fd6c461 to 7ae1fda Compare January 17, 2018 08:33

jtaekema-stripe reviewed Jan 18, 2018

View reviewed changes

docs/migrating.md Outdated

### Hard failures

Hard failures involve actual

Copy link

jtaekema-stripe Jan 18, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sentence fragment?

carolynvs approved these changes Jan 22, 2018

View reviewed changes

docs: Add installation.md, lots of tweaks

5e064a5

Assorted edits and wording tweaks, as well as including bash as type on most of the fenced code blocks. Also relocated assets into docs/assets from docs/img in order to accommodate docusaurus' expected layout.

sdboyer force-pushed the docusaurus branch from e0ec55d to 5e064a5 Compare January 23, 2018 14:54

sdboyer added 4 commits January 23, 2018 11:06

docs: First pass on docusaurus

430c48a

docs: Templates and CSS tweaks to docusaurus

f10e951

docs: new release announcement, CSS fixes

64d7f61

docs: Rework Gopkg.toml docs significantly

879f6ca

This was nominally to incorporate prune docs, but it became a broader rewrite that was really needed, anyway.

sdboyer merged commit 879f6ca into golang:master Jan 24, 2018

sdboyer added a commit that referenced this pull request Jan 24, 2018

docs: Incorporate massive docs update w/new site

4a3baf8

Closes #1499.

sdboyer deleted the docusaurus branch January 24, 2018 05:09

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[WIP] Add a mountain of docs #1499

[WIP] Add a mountain of docs #1499

sdboyer commented Jan 1, 2018 •

edited

Loading

bacongobbler Jan 3, 2018

sdboyer Jan 3, 2018

jmank88 Jan 3, 2018

sdboyer Jan 3, 2018

ibrasho Jan 4, 2018

sdboyer Jan 5, 2018

ibrasho Jan 4, 2018

sdboyer Jan 5, 2018

jtaekema-stripe Jan 18, 2018

carolynvs left a comment

carolynvs Jan 22, 2018

carolynvs Jan 22, 2018

carolynvs Jan 22, 2018

carolynvs Jan 22, 2018

sdboyer Jan 24, 2018

carolynvs Jan 22, 2018

sdboyer Jan 24, 2018

carolynvs Jan 22, 2018

sdboyer Jan 24, 2018


		## Override

		An override is a [`[[override]]`](Gopkg.toml.md#override) stanza in `Gopkg.toml`.

		### The Inference Phase

		The inference phase is where `dep init`'s behavior varies. By default, `dep init` will look in your codebase for metadata files from [other Go package management tools that it understands](https://github.com/golang/dep/tree/master/internal/importers), and attempt to automatically migrate the data in these files into concepts that make sense in a dep. Depending on the tool and the particular values dep finds, metadata from the tool may be treated as either:


		If you do encounter problems like this, `dep status` is your first diagnostic step; it will report what versions were selected for all your dependencies. It may be clear which dependencies are a problem simply from your building or testing error messages. If not, compare the `dep status` list against the versions recorded by your previous tool to find the differences.

		Once you've identified the problematic dependenc(ies), the next step is exerting appropriate controls over them via `Gopkg.toml`. (Note - this advice is intentionally terse; check out [Zen of Dep]() if you want a deeper understanding of how to optimally utilize dep's controls)

[WIP] Add a mountain of docs #1499

[WIP] Add a mountain of docs #1499

Conversation

sdboyer commented Jan 1, 2018 • edited Loading

What does this do / why do we need it?

What should your reviewer look out for in this PR?

Which issue(s) does this PR fix?

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

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sdboyer commented Jan 1, 2018 •

edited

Loading