Hub: Command Request: `hub issue view`

[emmabukacek]

As a user of hub,
I want to be able to view individual issues,
So I don't have to use my browser.

Requested Changes

• Add hub issue view <ISSUE #> command to view yml or json representation of issue

Apologies if this feature already exists already, but I couldn't find anything in the documentation. I'd be happy to take a crack at it; just want to make sure this issue is inline with hub's goals. Thanks!

[mislav]

Thank you for suggesting. This feature doesn't yet exist, but considering that hub issue (listing issues) and hub issue create exist, we do want to eventually have hub issue show <NUMBER> and hub issue edit <NUMBER>.

You're more than welcome to take a stab contributing this feature. (See existing implementations of commands/issue.go and commands/release.go). However, before you begin, it would be useful to flesh out how this feature should work:

• What format would the issue be presented in?
  
  
  
  • I'm leaning towards markdown output, since that's also the format issues are created and (eventually) edited in via hub issue create/edit.
  
  
  • Will the text output be wrapped for the terminal?
  
  
  • Did you have a reason for suggesting yml and json formats? For programmatic use, I can see how json might be useful, but we don't have any other hub commands outputing json yet. When would yml be useful?
  
  
  • If there are multiple supported output formats, how would a person pick between one?
  
  
• Would the issue content include the comment thread or not? If yes, how would comments be formatted?
• How would the state of the issue (open/close) be presented?
• How would assignees for the issue be presented?
• How would potential labels/projects/milestone be presented?
• If the issue is a Pull Request, would viewing it be supported through hub issue show?

See also #1465 #1686 #1407

[emmabukacek]

Thanks for the response! Apologies for my delay.

Will the text output be wrapped for the terminal?

I think so! I don't see any downsides unless you were piping that information into something else and you expected the data to be pristine, but at the same time, you would probably want a data format more suited for manipulation.

Did you have a reason for suggesting yml and json formats? For programmatic use, I can see how json might be useful, but we don't have any other hub commands outputing json yet. When would yml be useful?

Ah, so I jumped the gun a bit here. The reason for suggesting yml / json was because of my recent use of go-jira, but I conflated the acts of editing with the acts of viewing which have totally different implications. Apologies for the misdirection. Also, when I wrote this issue, I didn't realize hubs model was to pass in metadata as command line options with the file being solely responsible for the issue body, so that changes my thoughts a bit. Given the issues you linked (#1465 #1686 #1407), it sounds like having custom formatting for outputs would also be a nice feature, i.e. pipe JSON into jq or something similar, but that's probably more than I'm bargaining for with an MVP.

Would the issue content include the comment thread or not? If yes, how would comments be formatted?

Personally, I would like to see an issue holistically, i.e. all meta data, body, and comments, in one single response than to have to fetch things separately, but it sounds like hubs design philosophy is to have more single purpose commands, so my gut says no. However, I barely know the codebase, so take that answer with a grain of salt, hehe. If we did include them though, sounds like a key/value pair may suffice, i.e.

title: <ISSUE TITLE>
body: <ISSUE BODY>

comments:
  author:
  body:

Although, this suspiciously looks like yml now. :trollface: Did you have thoughts on this?

How would the state of the issue (open/close) be presented?
How would assignees for the issue be presented?
How would potential labels/projects/milestone be presented?

To echo what I said above, I'm not as familiar with hubs functionality as I probably need to be to answer this question, but whatever the case, I would opt for the solution with least surprise here. If we decided to include everything with view, then perhaps, like above, a key / value pair could work here? What are your thoughts?

If the issue is a Pull Request, would viewing it be supported through hub issue show?

I'm afraid I don't understand; when is a pull request an issue? Or do you mean if the issue is tied to a pull request?

CC: @mislav

[royels]

If no one's doing it, can I try taking a shot at implementing this?

[mislav]

@emmabukacek Apologies for my late reply. I had a lot of thoughts about this and I wanted to outline them all, but now I realize that the large mental overhead has prevented me from following up. Therefore, my thoughts condensed:

I think we should aim for a human-readable, markdown-like output format. A format for scripting would be great as well, but we might add a more generic query command in hub that outputs JSON or line-based output for use in automated scripts, so let's avoid replicating that functionality here.

I vote for an output format like:

# ISSUE TITLE
# [CLOSED] ISSUE TITLE (if an issue is closed)

* created by @USERNAME on DATE
* assignees: LIST
* ...

ISSUE BODY

## Comments:

### comment by @USERNAME on DATE

COMMENT BODY

when is a pull request an issue?

GitHub Pull Requests are basically Issues with extra fields, such as head, base, mergeable status, reviewers, etc. A command that displays an Issue could easily also accept and display a Pull Request as well; that's why I pointed it out as a potential feature.

@royels I would give @emmabukacek a chance to implement this if she is still interested, but you are welcome to take over as backup 🌟

[emmabukacek]

@mislav Not a problem at all!! Thanks for responding and thanks for clearing up the PR / Issue difference, too. :smile:

Also, super down with that output format. Clear and easy to parse.

As for who can take the reins on the work, I'm happy to bow out. I'm a bit full up at the moment and I'm a trash Go developer (As in, I've only ever _looked_ at Go code, :stuck_out_tongue: ), so @royels , it's all yours if you're game! I just wanted to get the ball rolling. :smile:

Let me know if I can help out at all! Thanks for volunteering @royels and thank you @mislav for asking clear questions to determine how we should ship this!

[royels]

So this is what I've done so far UI-wise: (attachment is the output of bin/hub issue view 1032)

Does this look good?

[mislav]

hub issue show is now live https://github.com/github/hub/commit/5346928ac4603712d982694a498fd5bb2c225b8a