Improve help text #78

peterbourgon · 2016-12-30T19:47:22Z

Sorry for this big change. I think it's a big improvement. First, I restructured how commands work.

Commands are now structs that implement a command interface
This allows commands to define their own set of parameters (flags)
Those struct members (params, flags) are bound to flags with a Register function
Run is a method on the command struct, with access to the parameters

This allowed me to make a lot of consistency improvements.

Deglobalize some things (yay)
Good news: dep foo -v ... works as expected
Bad news: dep -v foo ... stopped working — but that was weird anyway
Good news: dep foo -h works and looks consistent
Bad news: dep help foo doesn't exist anymore — but that was weird anyway

With all of that in place, I was able to audit and refactor all of the help texts. I think they're a lot better. Please take a look at any commands you feel particularly close to, and make sure I didn't write any lies. The biggest individual change was that I moved all of the ensure usage examples to a special flag, ensure -examples. I hope that's acceptable.

If I screwed anything else up, please accept my apologies.

Closes #73.

peterbourgon · 2016-12-30T19:48:15Z

Sample output!

ugh ~ dep
Usage: dep <command>

Commands:

  init    Initialize a new project with manifest and lock files
  status  Report the status of the project's dependencies
  ensure  Ensure a dependency is vendored in the project
  remove  Remove a dependency from the project

ugh ~ dep status -h
Usage: dep status [package...]

With no arguments, print the status of each dependency of the project.

  PROJECT     The import path of the dependency
  CONSTRAINT  The version constraint for the dependency, from the manifest
  VERSION     The version chosen for the dependency, from the lock
  REVISION    The VCS revision of the chosen version
  LATEST      The latest VCS revision available for the dependency
  PKGS USED   The number of packages (dependencies) used by this package

With one or more explicitly specified packages, or with the -detailed flag,
print an extended status output for each dependency of the project.

  TODO    Another column description.
  FOOBAR  Another column description.

Status returns exit code zero if all dependencies are in a "good state".

Flags:

  -detailed  report more detailed status (default: false)
  -dot       output the dependency graph in GraphViz format (default: false)
  -f         output in text/template format (default: <none>)
  -json      output in JSON format (default: false)
  -missing   only show missing dependencies (default: false)
  -modified  only show modified dependencies (default: false)
  -old       only show out-of-date dependencies (default: false)
  -unused    only show unused dependencies (default: false)
  -v         enable verbose logging (default: false)

ugh ~

freeformz · 2017-01-03T23:49:56Z

LGTM. I would like to see the return of dep help <cmd>, but that doesn't have to happen as part of this change.

sdboyer

basic refactors look good, though haven't actually tested it locally just yet.

mostly some nits on the actual helptext.

thanks again for doing this, Peter!

sdboyer · 2017-01-04T01:10:30Z

ensure.go

-
-Package specs:
-	<path>[:alt location][@<version specifier>]
+const ensureShortHelp = `Ensure a dependency is vendored in the project`


I think it might be good to just add one word:

Ensure a dependency is safely vendored in the project

"safely" will let people know there's some work being done there beyond simply fetching a project, and is amorphously indicative of the general kind of work that's happening.

sdboyer · 2017-01-04T01:11:50Z

ensure.go

+Ensure is used to fetch project dependencies into the vendor folder, as well as
+to set version constraints for specific dependencies. It takes user input,
+solves the updated dependency graph of the project, writes any changes to the
+manifest and lock file, and downloads dependencies to the vendor folder.


"downloads dependencies" is slightly misleading, as it's often/usually doing a copy of something that may have been downloaded long ago. Maybe:

places dependences in the vendor directory.

instead?

sdboyer · 2017-01-04T01:12:27Z

ensure.go

+const ensureExamples = `
+dep ensure
+
+    Solve the project's dependency graph, and download all dependencies to the


repeat of above re: "download"

sdboyer · 2017-01-04T01:13:11Z

ensure.go

+    specified there. Otherwise, use the most recent version that can satisfy the
+    constraints in the manifest file.
+
+dep ensure -update


we haven't actually implemented this flag yet - probably should make a note of that in the helptext?

Ack; actually I have just deleted all references to it, I think that's easier.

sdboyer · 2017-01-04T01:14:37Z

ensure.go

+    Same as above, but choose any release matching 0.9.x, preferring latest. If
+    a constraint was previously set in the manifest, this resets it.
+
+dep ensure github.com/heroku/rollrus@^0.9.1


supernit: i'd like carat above tilde, as it's the form we prefer people to use, so i'd like them to read it first

Absolutely!

sdboyer · 2017-01-04T01:15:44Z

ensure.go

+
+dep ensure github.com/heroku/rollrus
+
+    Update a specific dependency to the latest version allowed by the manifest,


this isn't actually a supported form right now; even though it was fixed in the other PR, we just haven't dealt with the single-dep update case at all yet

Ack; scratching, re: below.

sdboyer · 2017-01-04T01:19:05Z

ensure.go

+dep ensure github.com/heroku/rollrus
+
+    Update a specific dependency to the latest version allowed by the manifest,
+    including all of its transitive dependencies.


i don't think we'd ever actually be able to support this. while we can allow specifying multiple individual deps for update, we can't readily do all the transitive deps of a named dep, too. (a structural refactor in gps - sdboyer/gps#44 - may enable it, but even then, i'm not sure it's a good idea) plus, would this refer to the transitive dependencies that are uniquely the deps of the named project? or would it update shared/diamond deps, as well? this gets complicated.

for now, it might just be best to drop this whole individual example, until we sort out how we want it to work.

Ack; scratching this example altogether.

sdboyer · 2017-01-04T01:20:13Z

ensure.go

-	ensureCmd.flag.Var(&overrides, "override", "Interpret specified constraint(s) as override(s) rather than normal constraints")
+    Fetch the dependency from a different location.
+
+dep ensure github.com/heroku/rollrus==1.2.3  # 1.2.3 exactly


let's drop this whole example, we actually got rid of the double-operator form entirely, with the intention of figuring out a different way to express the same idea later

Ack, dropping both double-operator examples and the text.

sdboyer · 2017-01-04T01:21:40Z

init.go

+
+Note: init may use the network to solve the dependency graph.
+
+Note: init does NOT vendor dependencies. See dep ensure.


we may make it vendor deps sometime soon - maybe make this say

init does NOT vendor dependencies (for now).

?

sdboyer · 2017-01-04T01:22:24Z

main.go

-	Show documentation for the dep tool or the specified command.
-	`,
-	})
+			// Easy peasy livin' breezy.


🏄‍♀️🌻

- short/long should not embed leading/trailing newlines - Normalize grammar in short texts, and remove trailing periods - Remove tabs from strings that will be printed to terminal - Use tabwriter to print table of subcommands

Sorry for this big change. I think it's a big improvement. First, I restructured how commands work. - Commands are now structs that implement the command interface - Flags are bound to parameters in the command struct - Run is a method on the command struct, with access to flag vars This allowed me to make a lot of consistency improvements. - Good news: dep foo -v ... works - Bad news: dep -v foo ... stopped working (but that was weird) - Good news: dep foo -h works and looks consistent - Bad news: dep help foo doesn't exist anymore (but that was weird) With all of that in place, I was able to audit and refactor all of the help texts. I think they're a lot better. The biggest individual change was that I moved all of the ensure usage examples to a special flag, ensure -examples. I hope that's acceptable. If I screwed anything else up, please accept my apologies.

sdboyer · 2017-01-04T12:22:38Z

ensure.go


-dep ensure github.com/heroku/rollrus
+dep ensure github.com/heroku/rollrus@^0.9.1


shit, i missed this on my first pass - in the examples, we should use something > 1.0.0. The rules for the unary constraint operators change below 1.0.0, and I don't think we want people focused on that in the simplest of help text contexts.

sdboyer · 2017-01-04T12:27:26Z

ensure.go

 dep ensure -override github.com/heroku/rollrus@^0.9.1

    Forcefully and transitively override any constraint for this dependency.
-	This can inadvertantly make your dependency graph unsolvable; use sparingly.
+    This can inadvertantly make your dependency graph unsolvable; use sparingly.


Also missed this, sorry - the problem with overrides isn't that they make the depgraph unsolvable (indeed, the opposite - they're the sledgehammer you use when you can't solve the degraph any other way). Here's an alternative:

Overrides are powerful, but they are harmful over the long term. They should be used as a last resort, especially if any packages in your project may be imported by others.

sdboyer suggested changes Jan 4, 2017

View reviewed changes

Peter Bourgon added 5 commits January 4, 2017 13:18

First pass at normalizing help texts

01c2acf

- short/long should not embed leading/trailing newlines - Normalize grammar in short texts, and remove trailing periods - Remove tabs from strings that will be printed to terminal - Use tabwriter to print table of subcommands

One clarification to init's short help

071e9f8

Update column descriptions in status after clarification

02b0f4c

Review feedback

92b700e

sdboyer reviewed Jan 4, 2017

View reviewed changes

peterbourgon force-pushed the 73-improve-help branch from 9882c28 to 92b700e Compare January 4, 2017 12:22

sdboyer reviewed Jan 4, 2017

View reviewed changes

Peter Bourgon added 2 commits January 4, 2017 13:27

Further review feedback

42bb390

Further review feedback re: overrides

36d935b

sdboyer approved these changes Jan 4, 2017

View reviewed changes

Tweak my text changes just a little bit more

5c4faa8

sdboyer merged commit 3e21bee into master Jan 4, 2017

jessfraz deleted the 73-improve-help branch January 4, 2017 23:09

sdboyer mentioned this pull request Jan 5, 2017

Implement "update" behavior #83

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve help text #78

Improve help text #78

peterbourgon commented Dec 30, 2016 •

edited

peterbourgon commented Dec 30, 2016 •

edited

freeformz commented Jan 3, 2017

sdboyer left a comment

sdboyer Jan 4, 2017

peterbourgon Jan 4, 2017

sdboyer Jan 4, 2017

peterbourgon Jan 4, 2017

sdboyer Jan 4, 2017

peterbourgon Jan 4, 2017

sdboyer Jan 4, 2017

peterbourgon Jan 4, 2017 •

edited

sdboyer Jan 4, 2017

peterbourgon Jan 4, 2017

sdboyer Jan 4, 2017

peterbourgon Jan 4, 2017 •

edited

sdboyer Jan 4, 2017

peterbourgon Jan 4, 2017

sdboyer Jan 4, 2017

peterbourgon Jan 4, 2017

sdboyer Jan 4, 2017

peterbourgon Jan 4, 2017

sdboyer Jan 4, 2017

sdboyer Jan 4, 2017

sdboyer Jan 4, 2017 •

edited


		dep ensure github.com/heroku/rollrus

		Update a specific dependency to the latest version allowed by the manifest,


		Note: init may use the network to solve the dependency graph.

		Note: init does NOT vendor dependencies. See dep ensure.


		dep ensure github.com/heroku/rollrus
		dep ensure github.com/heroku/rollrus@^0.9.1

Improve help text #78

Improve help text #78

Conversation

peterbourgon commented Dec 30, 2016 • edited

peterbourgon commented Dec 30, 2016 • edited

freeformz commented Jan 3, 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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

peterbourgon Jan 4, 2017 • edited

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 Jan 4, 2017 • edited

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 Jan 4, 2017 • edited

Choose a reason for hiding this comment

peterbourgon commented Dec 30, 2016 •

edited

peterbourgon commented Dec 30, 2016 •

edited

peterbourgon Jan 4, 2017 •

edited

peterbourgon Jan 4, 2017 •

edited

sdboyer Jan 4, 2017 •

edited