Skip to content

More specific help summaries#98

Merged
mislav merged 5 commits intomasterfrom
more-specific-help-summaries
Nov 25, 2019
Merged

More specific help summaries#98
mislav merged 5 commits intomasterfrom
more-specific-help-summaries

Conversation

@outofambit
Copy link
Copy Markdown
Contributor

  • expand root help summary
  • add specifics to issue help summary
  • add specifics to pr help summary

@outofambit outofambit requested a review from ampinsk November 20, 2019 23:12
Copy link
Copy Markdown
Contributor

@mislav mislav left a comment

Choose a reason for hiding this comment

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

Thank you for the suggestions @outofambit!

var prCmd = &cobra.Command{
Use: "pr",
Short: "Work with pull requests",
Short: "Create, view, and checkout pull requests",
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

It's definitely more clear what this offers! I wonder whether we will have to indefinitely have to keep expanding this sentence as we add more actions in the future: update, merge, close, comment on, etc. 🤔 but we haven't reached that bridge yet.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

yeah i was thinking about that too. maybe some things can be grouped under "edit" or "manage pull requests"? or we could just bring back the "work with" phrase at the end of the list

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Yeah I think I like this for now, and we can reassess as we add things. Can easily see us adding "manage" or "edit" as a grouping of things in the near future

command/root.go Outdated
Long: `Integrate GitHub into your command-line workflow, starting
with issues and pull requests.

(Note: gh is in a very alpha phase.)`,
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I don't think we need to explicitly spell this out, people should already be aware of this when they're downloading gh?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

they should be, but i didn't see "alpha phase" until i happened to look at the readme for gh-cli. and while i knew that intuitively, it was still helpful to spell it out. i definitely don't feel strongly about this one though!

Copy link
Copy Markdown

@ampinsk ampinsk Nov 21, 2019

Choose a reason for hiding this comment

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

I had two separate very conflicting ideas here 😆

  1. I feel like we could imply this through displaying the version number. Seeing 0.x would imply "pre-release".

  2. Alternatively, we could lean into this as maybe a "greeting" message if that's not too weird? Something like:

Work seamlessly with GitHub from the command line. Welcome to the alpha for gh, let us know your feedback at [email]

cc @billygriffin curious to hear your thoughts here

Copy link
Copy Markdown
Contributor

@billygriffin billygriffin Nov 21, 2019

Choose a reason for hiding this comment

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

I really like the callout on how to give feedback! I might opt for something like this to avoid the use of "alpha," which may not be universally understood or may mean different things to different people:

Work seamlessly with GitHub from the command line. GitHub CLI is in early stages of development, and we'd love to your feedback at [feedback]

I'm curious how we'd use feature preview for this if we went this route. cc: @ohitsmekatie

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

I love that! I propose we follow up on the feedback piece in a later PR so we can get these more straightforward fixes in, and suggest we go with this piece alone until then:

Work seamlessly with GitHub from the command line.

command/root.go Outdated
Short: "GitHub CLI",
Long: `Work with GitHub from your terminal`,
Long: `Work seamlessly with GitHub from your command-line, starting
with issues and pull requests.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

These lines shouldn't be indented, since we're in a Go string literal, and the indent will take effect in help text:

$ make && gh
Work seamlessly with GitHub from your command-line, starting
        with issues and pull requests.

        (Note: gh is in a very alpha phase.)

@ampinsk
Copy link
Copy Markdown

ampinsk commented Nov 22, 2019

I just pushed a commit to tweak that top line summary since @outofambit is out for a few days!

Copy link
Copy Markdown

@ampinsk ampinsk left a comment

Choose a reason for hiding this comment

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

This looks good to me, but I'll wait to see if any of the devs spot anything blocking!

Copy link
Copy Markdown
Contributor

@mislav mislav left a comment

Choose a reason for hiding this comment

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

Looking great, thank you @ampinsk @outofambit!

@mislav mislav merged commit f39cf28 into master Nov 25, 2019
@mislav mislav deleted the more-specific-help-summaries branch November 25, 2019 10:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants