CLI UX need refinements about git-bug

[MichaelMure]

Thanks, will do !

I recently switched to use cobra as a lib for command line parsing and stuff. Did you check ? The root command should list properly the subcommands as well as provide suggestion for typos.

git bug commands was designed to be able to build command line completion tool and to generate documentation, but now that cobra does that (check the doc folder), it might be removed.

I guess I should follow the same pattern for other commands as well ? For labels it should be:
git bug label <id> list the labels
git bug label add <id> add a label
git bug label remove <id> remove a label

That's quite a lot of keystrokes though...

I was also thinking about having a command like git bug select <id> that would select a bug as default for future edit with other commands. Good or bad idea ?

[ermik]

As long as there is a Y/N prompt for any default options — they wouldn't hurt. Keystrokes are handles by shell aliases, which just needs to be explained to some people.

Project seems awesome.

[afranke]

I guess I should follow the same pattern for other commands as well ?

Yes, consistecny is important and completion should reduce the amount of keystrokes anyway.

I was also thinking about having a command like git bug select that would select a bug as default for future edit with other commands. Good or bad idea ?

Good idea. git already has a few interactive subcommands like git add -p which you may want to mimic.

[MichaelMure]

Project seems awesome.

\o/

Just so you know, I'm waiting for the core feature to stabilize and to have a consistent plan for all the commands to tackle this problem.

Another question, should git bug simply run the interactive UI (so git bug termui would be removed) ? I expect that most people would use the interactive UI so it would make sense to launch it easily. It does hide a bit the command's help for the newcomer though ...

UX peoples, please send help :)

[ermik]

Run the interactive by default. Provide --ci and similar options to allow no-TTY execution (e.g. the build / continuous integration system files bugs on failure automatically).

[jlegeny]

I'd like to suggest some additional commands for actions that do not seem currently possible:

• git bug status to see what bugs were added since the latest push
• git bug reset to undo changes to a bug
• git bug remove to delete a bug

My main point is that it is important to be able to modify the state in all possible ways before it is pushed to the remote.

[MichaelMure]

@jlegeny that's a good point. Technically if possible to implement status and reset by comparing or copying the references in refs/bugs/* and refs/remotes/<remote>/bugs/*. That also mean that the actual status can be different if you use multiple remote.

[MichaelMure]

With the previous comments, I tried to summon my inner UX guy and devise a plan:

Current situation

• git bug: show help

• git bug ls: list bugs

• git bug push [<remote>]: push to remote

• git bug pull [<remote>]: pull from remote

• git bug termui: launch the terminal UI

• git bug webui [-p 1234]: launch the web UI

• git bug new [-t "title"] [-m "message"]: new bug

• git bug comment <id> [-m "message"]: add comment

• git bug label <id> [-r] [<label>...]: add/remove labels

• git bug open <id>: change status to OPEN

• git bug close <id>: change status to CLOSE

Problems/questions

• missing git bug title
• should git bug run the termui instead of showing the help ?
• merge open and close into a status command ?
• new is not a verb
• label has a different UX
• can't have a select mechanism with the current label --> what is the id, what is a label ?
• is it better to favor short commands or complete set of features for the CLI ? (e.g. git bug title to edit, or git bug title to show the current title and git bug title change to change it) ?

New shinny plan

As before

• git bug push [<remote>]: push to remote
• git bug pull [<remote>]: pull from remote
• git bug termui: launch the terminal UI
• git bug webui [-p 1234]: launch the web UI

Changed

• git bug: list bugs
• git bug comment [<id>]: show all comments
• git bug comment add [<id>] [-m "message"]: add comment
• git bug label [<id>]: show all labels
• git bug label add [<id>] <label>...: add labels
• git bug label rm [<id>] <label>...: remove labels

Removed

• git bug new: renamed to add
• git bug ls: removed in favor of git bug

Added

• git bug add [-t "title"] [-m "message"]: new bug
• git bug title [<id>]: show the title
• git bug title edit [<id>]: edit the title
• git bug diff [<id>] [<remote>]: show what bugs have been added/changed regarding the default or explicit remote. No select mechanism here, the is a filter.
• git bug status [<id>]: show the current status
• git bug status open [<id>]: change status to open
• git bug status close [<id>]: change status to closed
• git bug reset <id> [<remote>]: clear the changes of a bug to match the bug of a remote
• git bug rm <id> [<remote>]: remove a bug locally or on a remote

select mechanism

• git bug select <id>: select a bug for implicit editing later
• using a command with an explicit id discard the selected id
• automatic select with new/add ?
• instead of an id, a filter could be used (e.g.: git select "UX refinement"), and it would work if only one bug match. Actually no, it's weird to craft a query that would only give one result
• should display a summary of the selected bug when successfully selecting to avoid mistakes
• there is still a potential conflict when a command has both an id and arbitrary args (e.g. git bug label add). That will require a test to see if the first arg could be a bug id or a prefix to a bug id. There is really unlikely case where it could be a problem though: git bug label add cafe when we have a bug with an id starting with cafe.

What do you all think ?

[j-f1]

How about git bug label and git bug unlabel?

[MichaelMure]

@j-f1 you would have no commands to see the label of a bug. Also, consistency and predictability are paramount for a good UX.

[MichaelMure]

The downside of this new approach is that the commands are quite long. git bug title edit is 18 characters without the new title itself nor a bug id/prefix.

This is mitigated by the command auto-completion and the termUI though. Another way would be to have a short alias to the git-bug binary. Another way would be to have a git bug shell command that would spawn a terminal where commands would be simply title edit and so on.

[MichaelMure]

Alright, I made the "safe" changes, as detailed above.

The missing parts are either completely new commands or things I'm unsure about. Please have a test and give me some feedback.

[adamslc]

What are your plans for a git bug config command? To start off the conversation, here is an incomplete list of things that might possibly need to be configured. Note that I'm not arguing that everything on this list should actually be implemented.

• Default remote
• Set of possible labels
• Possibly move git bug bridge configure under here?
• Default new bug and comment templates
• Keybindings in termui
• Author data specific to git bug. I'm not sure if this exists?

Also, I think that having connivance flags to update the config from other commands makes sense. In #62 I suggested using -d and --set-default in git bug push to get and set the default remote. I'm now convinced that those aren't the right flags to use (looks to much like delete), but I still think that this is important functionality. Perhaps mirroring git push and using -u and --set-upstream would makes sense.

[j-f1]

Why not use the regular git config command and name the settings git-bug.foo?

[adamslc]

For some settings, I think that makes a lot of sense, but not all of these configuration options can be stored in a local config file. In particular, modifying the set of allowed labels seems like it needs to be more closely integrated with git bug.

[MichaelMure]

Let's move the config discussion here: #63

[MichaelMure]

I move the missing part in separate discussion, I guess we can consider the matter here resolved.

#64
#65
#66