Bring README up to date after #489 #991
Conversation
README.md
Outdated
| $ dep ensure -add github.com/some/project github.com/other/project/[email protected] | ||
| ``` | ||
|
|
||
| `dep ensure -add`'s behavior varies slightly depending on whether there are already rules in `Gopkg.toml` for the named project(s), as well as whether you already import packages from the named project(s). See `dep ensure -examples` for more sample combinations. |
There was a problem hiding this comment.
I'm confused about how the -add command works. I just tried it out and it didn't append to my Gopkg.toml like the examples said it would.
I have more thoughts but wanted to clear that up before babbling on. 🤓
There was a problem hiding this comment.
Just found #989 (comment). Since updating the manifest isn't implemented yet, the -examples should be updated remove the inaccurate help text.
There was a problem hiding this comment.
👍
i'll do that as an atomic commit so it's easy to revert later
There was a problem hiding this comment.
so, that was easier than i thought - #994. maybe just leave this?
README.md
Outdated
| 2. Add a version constraint on the project to `Gopkg.toml` (Optional, but recommended) | ||
| 3. Run `dep ensure` | ||
|
|
||
| `dep ensure -add` provides some CLI sugar to ease this process: |
There was a problem hiding this comment.
Since ensure is in a half implemented state, we should say exactly what the "sugar" is and it replaces all of steps 1-3, e.g. Alternatively you can run dep ensure -add to add the project to Gopkg.lock and your vendor directory, then you can immediately start using the project in your code.
There was a problem hiding this comment.
the only core behavior missing from ensure's implementation is hoisting a constraint up out of the lock. maybe i should just blow some time on getting that last bit of ensure done tonight 🤔
even then, though, that's the problem - dep ensure -add doesn't actually replace step 1. it's just a stopgap for it.
There was a problem hiding this comment.
Now that -add is a fully operational battlestar, my comments are all out-of-date. 😀 Thanks for pushing that through!!!
Since this is the quickstart/readme, how about telling people just the best practice:
- Run
dep ensure -add github.com/foo/bar. This adds a constraint for the latest version to your Gopkg.toml, then updates the lock and vendor directory. - Import and use the package in your code. ✨
Sparkles optional, but highly recommended.
README.md
Outdated
| $ dep ensure | ||
| ``` | ||
| 1. `import` a package from the project in one of your `*.go` source files | ||
| 2. Add a version constraint on the project to `Gopkg.toml` (Optional, but recommended) |
There was a problem hiding this comment.
Maybe reword that so that it's more clear what they should add? e.g. Add a [[constraint]] entry...
Revert this once we get in and implement that.
@ashleymcnamara is my hero
This reverts commit ed6f5ea.
|
@carolynvs are you good with this now, then? |
|
Doh! I need to learn to not reply to comments that have been hidden due to new commits... I was hoping we could tweak the recommendation for adding a dependency:
It's not a huge deal, and we can merge without it, but I think it will help avoid confusion for new users. |
|
ahh ok - yeah, that's fair, i had a similar thought while writing that. yeah, can tweak. |
|
@carolynvs how dat? |
What does this do / why do we need it?
README was out of date after merging of #489
What should your reviewer look out for in this PR?
My big question would be whether the diagram is sufficiently helpful to be justified.
Other than that, making sure that I haven't been too cryptic 😄
Fixes #565 😄 😄 😄