-
Notifications
You must be signed in to change notification settings - Fork 1k
Conversation
docs/Gopkg.toml.md
Outdated
|
||
## `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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
typo: information
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
ah, thanks!
docs/FAQ.md
Outdated
-- | ||
id: faq.md | ||
title: FAQ | ||
-- |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Most of these have three dashes, but this one has two and another place has four. Should they all be three?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
ah yes, they should, thanks
docs/Gopkg.toml.md
Outdated
* [`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. | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
prune
settings?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
i thought i'd added that in there, hmm, i'll make sure it gets taken care of
docs/new-project.md
Outdated
|
||
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](). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this link missing intentionally?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
docs/migrating.md
Outdated
|
||
### Hard failures | ||
|
||
Hard failures involve actual |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
sentence fragment?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I just have some minor comments that can easily be addressed later.
@@ -156,7 +194,7 @@ codename = "foo" | |||
name = "github.com/user/project" | |||
version = "1.0.0" | |||
|
|||
[constraint.metadata] | |||
[metadata] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Did this change? I thought we needed the prefix?
docs/glossary.md
Outdated
|
||
## Override | ||
|
||
An override is a [`[[override]]`](Gopkg.toml.md#override) stanza in `Gopkg.toml`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It's worth repeating here that overrides only apply to the current project.
### 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: | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We should clarify that we don't (yet) take into account external config in your dependencies and only import from the current project.
docs/migrating.md
Outdated
|
||
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) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Zen of dep is missing a URL
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
it's also missing a writeup right now :(
|
||
* 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). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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-editingGopkg.lock
, it is at least a feature request, and likely a bug.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
modified, thanks
* 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`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
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:
Gopkg.lock
docsdefer to followup:
dep in monoreposreview FAQ for items that are now better-covered elsewhereRetouchGopkg.toml
docsZen of constraints/locks guideWhat 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