Closed Bug 1576812 Opened 5 years ago Closed 5 years ago

mach try fuzzy is completely inscrutable to me

Categories

(Developer Infrastructure :: Try, task, P2)

Product:
Developer Infrastructure
Component:
Try
Type:
task

Tracking

(Not tracked)

Status:
RESOLVED FIXED

People

(Reporter: mstange, Assigned: ahal)

Details

Attachments

(3 files)

Bug 1576812 - [tryselect] Improve mach try fuzzy documentation
47 bytes, text/x-phabricator-request
Details | Review
Bug 1576812 - [tryselect] Increase width of fzf preview pane in |mach try fuzzy|
47 bytes, text/x-phabricator-request
Details | Review
Bug 1576812 - [tryselect] Re-order header shortcuts in an order that makes more sense (given they don't all fit), r?iain
47 bytes, text/x-phabricator-request
Details | Review

Once a year I decide to give mach try fuzzy another try, and every time I do, I'm left absolutely stumped by the UI. And then I resort to the old try syntax and waste resources by doing things like -u all. But at least the old try syntax I can understand.

Since I started to write this bug report, I have familiarized myself a little more with the UI, but what follows below is my experience report. Maybe we can save others from similar grief by making changes to the documentation.

Anyway, here goes:

Here's what mach help try fuzzy says (excerpt):

$ mach help try fuzzy
usage: mach [global arguments] try fuzzy [command arguments]

Select which tasks to use with fzf.

This selector runs all task labels through a fuzzy finding interface.
All selected task labels and their dependencies will be scheduled on
try.

Keyboard Shortcuts
------------------

When in the fuzzy finder interface, start typing to filter down the
task list. Then use the following keyboard shortcuts to select tasks:

  accept: <enter>
  cancel: <ctrl-c> or <esc>
  cursor-up: <ctrl-k> or <up>
  cursor-down: <ctrl-j> or <down>
  toggle-select-down: <tab>
  toggle-select-up: <shift-tab>
  select-all: <ctrl-a>
  deselect-all: <ctrl-d>
  toggle-all: <ctrl-t>
  clear-input: <alt-bspace>

There are many more shortcuts enabled by default, you can also define
your own shortcuts by setting `--bind` in the $FZF_DEFAULT_OPTS
environment variable. See `man fzf` for more info.

Having <enter> as the first item in the list was my first point of confusion. Does "accept" mean "accept the selected task into the list", or does it mean "commit the entire list and kick off the try job"? It means the latter. Please clarify this.

Next, I have no idea what the difference between "selecting" and "toggling" is. Apparently every list item has four pieces of state: Present in the main view, under the cursor or not (this is the highlighted row), selected or not (this is marked with a > at the beginning of the line), and it can be present in the list on the right (which is too narrow, by the way). Which piece of state is controlled by what? Which piece of state influences which try jobs are going to be run?

"There are many more shortcuts enabled by default, you can also define your own shortcuts" - this blurb almost made me cry. I haven't figured out the first thing about how to actually use this yet, and you're telling me I can define additional shortcuts? This is not what I need right now!

... (Here's where I find out that tab selects things.) ...

Ok, what does it mean that, when nothing is selected, the item under the cursor shows up in the list on the right anyway? And moving the cursor around keeps changing what's shown there? And then once I select one item, this behavior stops and what's under the cursor no longer shows up in the list?! Oh wait WHAT, there are two levels of > markers? What does it mean!?!

... (Here I send off my first successful mach try fuzzy job.) ...

Ok, let's gather our bearings.

The instructions as written sound like the flow is:

  1. Type to filter (sure, I can do that.)
  2. Accept. (Wait! This sends off an empty list!)

This has happened to me more than once.

More helpful instructions would be:

  1. Type to filter.
  2. Select jobs you want, either one-by-one using tab, or all at the same time, using Ctrl+A.
  3. If you want more jobs that are not in the current filter, press backspace until the filter is empty again, and type your new filter.
  4. Add more jobs using tab or Ctrl+A.
  5. Repeat until you're happy with the list of selected jobs. Selected jobs are indicated both by a > and by being present in the list on the right.
  6. Press enter to commit the list and kick off the try push.

Other pieces of information that would have helped me are:

  • Only selected jobs will be run (plus any the jobs they depend on). The list of jobs to run is on the right. Just because a job matches the current filter and is shown in the list on the left does not mean it is part of the selected set. It needs to be selected first so that it shows up on the right. The selected jobs also carry a > marker in the list on the left.
  • "toggle-select" means "Select or deselect the row under the cursor". Tab automatically moves the cursor to the next row. If you would like to move to the previous row after toggling, press shift+tab instead. There is no shortcut that toggles the selection without moving the cursor.
  • Only press enter once you're happy with your selection.

Also, the fact that dependencies are run automatically should be emphasized, with an example. Here's one: "If you want to run reftests, you don't need to select build jobs. The necessary builds will automatically be run because the dependency between build and reftest job is known. And the reftest job name indicates the platform. For example, here's one way to kick off a try run full of reftests: 1. Run mach try fuzzy. 2. Enter '-reftest into the filter. Now the main list will show all available jobs that contain the substring reftest 3. Press Ctrl+A to select all those jobs. 4. Press Enter to accept the list."

Thank you, this is a fantastic write-up! I've been meaning to improve the try fuzzy docs for some time and this will be an excellent source to work from.

Type: defect → task
Priority: -- → P2

Also worth pointing out that the source-docs might be a tiny bit better here (but still far from perfect):
https://firefox-source-docs.mozilla.org/tools/try/selectors/fuzzy.html

But --help is the first point of contact and should definitely be improved.

Semi-related: At the bottom of the fuzzy interface, there's a summary of shortcuts: accept: <enter>, cancel: <ctrl-c>, cursor-down: <ctrl-j>, cursor-up: <ctrl-k>, select-all: <ctrl-a>, toggle..

Unfortunately, even with the terminal maximized on my laptop, that's precisely where the summary ends: just before mentioning <tab>, the most important key in the interface. The first time I used try fuzzy, this slowed me down quite a bit.

Can we move toggle-select to the front of the list? As it stands, whenever I explain try fuzzy to somebody who hasn't used it before, I have to warn them to reduce their font size to reveal all the shortcuts.

Some notes on my experience as I was asked to provide feedback also:

  • I don't know what the difference is between --full and not; but I learned at some point that some of the things I want to run only show up when I use --full so now I always use it. (I work on Tier 2 stuff a lot so maybe that's why I wound up here?)
  • Because of fuzzing matching typing a substring will match unintended things, so I am petrified of trying to doing anything other than the manual process of picking jobs (meaning no CLI shortcuts like ./mach try fuzzy reftests). For example (this isn't a good example but it was the first one I found) say I want to run repackage-signing-msi jobs, so I filter with 'msi'. Oops you've always matched mar-signing. Does "msi" avoid this? No it does not. Okay guess I'll pick them manually....
  • Another example is filtering for 'mingw'
  • Another, even more fun example, is 'mingwclang webgl' because the webgl matches in the same string as the mingwclang!

Thanks everyone, great stuff!

(In reply to Tom Ritter [:tjr] from comment #4)

  • I don't know what the difference is between --full and not; but I learned at some point that some of the things I want to run only show up when I use --full so now I always use it. (I work on Tier 2 stuff a lot so maybe that's why I wound up here?)

With a handful of exceptions*, anything that runs on mozilla-central will show up by default. Otherwise it will require --full. The intention here is that the default set contains every task that could possibly cause you to get backed out.

* Exceptions include things that take a really long time (like ccov) or extremely resource constrained platforms (like Android hardware).

  • Because of fuzzing matching typing a substring will match unintended things, so I am petrified of trying to doing anything other than the manual process of picking jobs (meaning no CLI shortcuts like ./mach try fuzzy reftests). For example (this isn't a good example but it was the first one I found) say I want to run repackage-signing-msi jobs, so I filter with 'msi'. Oops you've always matched mar-signing. Does "msi" avoid this? No it does not. Okay guess I'll pick them manually....

Any search term prefixed with a single quote will be an exact match. So for example:
./mach try fuzzy -q "'msi"

would not match mar-signing.

You can also turn off fuzzy matching altogether by passing in -e/--exact. See:
https://firefox-source-docs.mozilla.org/tools/try/selectors/fuzzy.html#additional-arguments

You could alternatively set the FZF_DEFAULT_OPTS="--exact" environment variable to make this permanent.

I'd like to invite everyone here to provide feedback on the above patch. I'd recommend viewing the generated docs rather than the source file changes:

$ arc patch D44911
$ ./mach doc tools/tryselect
<navigate to the selectors/fuzzy page>

I've also improved the ./mach try fuzzy --help a bit.

Assignee: nobody → ahal
Status: NEW → ASSIGNED

Looks like Markus is still PTO for a couple weeks.

Tom, Iain.. I'll flag you both and land after the first person r+'es (I can always make follow-up commits too). Feel free to drop the review if you don't want it.

Keywords: leave-open
Pushed by ahalberstadt@mozilla.com:
https://hg.mozilla.org/integration/autoland/rev/8344d33bb2ba
[tryselect] Improve mach try fuzzy documentation r=iain
https://hg.mozilla.org/integration/autoland/rev/7b39d0ded1a3
[tryselect] Increase width of fzf preview pane in |mach try fuzzy| r=gbrown
Pushed by ahalberstadt@mozilla.com:
https://hg.mozilla.org/integration/autoland/rev/ec2cf40bc861
[tryselect] Re-order header shortcuts in an order that makes more sense (given they don't all fit), r=iain

I'm going to resolve this fixed for now.

But Markus, Tom if you guys want to provide feedback, you can see the new docs here:
https://firefox-source-docs.mozilla.org/tools/try/selectors/fuzzy.html

Feel free to re-open if you think further changes are needed.

Status: ASSIGNED → RESOLVED
Closed: 5 years ago
Flags: needinfo?(tom)
Flags: needinfo?(mstange)
Keywords: leave-open
Resolution: --- → FIXED

I understand it better!

Flags: needinfo?(tom)

I've finally taken a look - it's much better, thanks!

Flags: needinfo?(mstange)
Product: Firefox Build System → Developer Infrastructure
You need to log in before you can comment on or make changes to this bug.

Attachment

General

Creator:
Created:
Updated:
Size: