Bug 1576812 - [tryselect] Improve mach try fuzzy documentation r=iain

Differential Revision: https://phabricator.services.mozilla.com/D44911

--HG--
extra : moz-landing-system : lando

tools/tryselect/docs/selectors/fuzzy.rst

@@ -5,54 +5,157 @@ The fuzzy selector uses a tool called `fzf`_. It allows you to filter down all o
 from a terminal based UI and an intelligent fuzzy finding algorithm. If the ``fzf`` binary is not
 installed, you'll be prompted to bootstrap it on first run.
 
+
+Understanding the Interface
+---------------------------
+
+When you run ``mach try fuzzy`` an interface similar to the one below will open. This is `fzf`_.
+
+.. image:: fzf.png
+
+There's a lot to unpack here, so let's examine each component a bit more closely.
+
+   A. The set of tasks that match the currently typed-out query. In the above image only tasks that
+   match the query ``'linux64 mochibrochr`` are displayed.
+
+   B. The set of selected tasks. These are the tasks that will be scheduled once you hit ``Enter``.
+   In other words, if the task you want does not appear here, *it won't be scheduled*.
+
+   C. Count information of the form ``x/y (z)``, where ``x`` is the number of tasks that match the
+   current query, ``y`` is the total number of tasks and ``z`` is the number of tasks you have
+   selected.
+
+   D. The input bar for entering queries. As you type you'll notice the list of tasks in ``A``
+   starts to update immediately. In the image above, the query ``'linux64 mochibrochr`` is entered.
+   Correspondingly only tasks matching that query are displayed.
+
+In general terms, you first find tasks on the left. Then you move them over to the right by
+selecting them. Once you are satisfied with your selection, press ``Enter`` to push to try.
+
+
 Selecting Tasks
 ---------------
 
-Running ``mach try fuzzy`` without arguments will open up the ``fzf`` interface with all of the
-available tasks pre-populated on the left. If you start typing, you'll notice tasks are instantly
-filtered with a fuzzy match. You can select tasks by ``Ctrl+Click`` with the mouse or by using the
-following keyboard shortcuts:
+There are few ways you can select tasks. If you are feeling a bit overwhelmed, it might be best to
+stick with the mouse to start:
+
+   1. Enter a query (e.g ``mochitest``) to reduce the task list a little.
+   2. Scroll up and look for the task(s) you want.
+   3. ``Right-Click`` as many tasks as desired to select them.
+   4. Optionally delete your query, go back to step 1) and repeat.
+   5. Press ``Enter`` to push (or ``Esc`` to cancel).
+
+.. note::
+
+   Dependencies are automatically filled in, so you can select a test task without needing
+   to select the build it depends on.
+
+As you ``Right-Click``, notice that a little arrow appears to the left of the task label. This
+indicates that the task is selected and exists in the preview pane to the right.
+
+Once you are a bit more comfortable with the interface, using the keyboard is much better at quickly
+selecting tasks. Here are the main shortcuts you'll need:
 
 .. code-block:: text
 
-    Ctrl-K / Down  => Move cursor up
-    Ctrl-J / Up    => Move cursor down
+    Ctrl-K / Up    => Move cursor up
+    Ctrl-J / Down  => Move cursor down
     Tab            => Select task + move cursor down
     Shift-Tab      => Select task + move cursor up
     Ctrl-A         => Select all currently filtered tasks
     Ctrl-D         => De-select all currently filtered tasks
     Ctrl-T         => Toggle select all currently filtered tasks
-    Alt-Bspace     => Clear input
+    Alt-Bspace     => Clear query from input bar
+    Enter          => Accept selection and exit
+    Ctrl-C / Esc   => Cancel selection and exit
     ?              => Toggle preview pane
 
-Notice you can type a query, select some tasks, clear the query and repeat. As you select tasks
-notice they get listed on the right. This is the preview pane, it is a view of what will get
-scheduled when you're done. When you are satisfied with your selection, press ``Enter`` and all the
-tasks in the preview pane will be pushed to try. If you changed your mind you can press ``Esc`` or
-``Ctrl-C`` to exit the interface without pushing anything to try.
 
-Unlike the ``syntax`` selector, the ``fuzzy`` selector doesn't use the commit message to pass
-information up to taskcluster. Instead, it uses a file that lives at the root of the repository
-called ``try_task_config.json``. You can read more information in the :doc:`taskcluster docs
-</taskcluster/taskcluster/try>`.
+The process for selecting tasks is otherwise the same as for a mouse. A particularly fast and
+powerful way to select tasks is to:
+
+.. code-block:: text
+
+    Write a precise query => Ctrl-A => Alt-Bspace => Repeat
+
+As before, when you are satisfied with your selection press ``Enter`` and all the tasks in the
+preview pane will be pushed to try. If you change your mind you can press ``Esc`` or ``Ctrl-C`` to
+exit the interface without pushing anything.
 
-Extended Search
+.. note::
+
+   Initially ``fzf`` will automatically select whichever task is under your cursor. This is a
+   convenience feature for the case where you are only selecting a single task. This feature will be
+   turned off as soon as you *lock in* a selection with ``Right-Click``, ``Tab`` or ``Ctrl-A``.
+
+
+Writing Queries
 ---------------
 
-When typing in search terms, you can separate terms by spaces. These terms will be joined by the AND
-operator. For example the query:
+Queries are built from a series of terms, each separated by a space. Terms are logically joined by
+the AND operator. For example:
 
 .. code-block:: text
 
-    windows mochitest
+    'windows' 'mochitest'
+
+This query has two terms, and is the equivalent of saying: Give me all the tasks that match both the
+term ``'windows'`` and the term ``'mochitest'``. In other words, this query matches all Windows
+mochitest tasks.
 
-Will match tasks that have both the terms ``windows`` AND ``mochitest`` in them. This is a fuzzy match so the query:
+The single quotes around each term tell ``fzf`` to use exact substring matches, so only
+tasks that contain both the literal string ``windows`` AND the literal string ``mochitest`` will be
+matched. For convenience, the trailing quote is optional:
+
+.. code-block:: text
+
+    'windows 'mochitest
+
+This query is exactly the same as the one before.
+
+.. note::
+
+    From here on out the trailing quote will be omitted from examples.
+
+Another thing to note is that the order of the terms makes no difference, so ``'windows 'mochitest``
+and ``'mochitest 'windows`` are equivalent.
+
+
+Fuzzy terms
+~~~~~~~~~~~
+
+If a term is *not* prefixed with a single quote, that makes it a fuzzy term. This means the
+characters in the term need to show up in order, but not in sequence. E.g the fuzzy term ``max``
+would match the string ``mozilla firefox`` (as first there is an ``m``, then an ``a`` and finally an
+``x``), but not the string ``firefox by mozilla`` (since the ``x`` is now out of order). Here's a
+less contrived example:
 
 .. code-block:: text
 
     wndws mchtst
 
-Would likely match a similar set of tasks. The following modifiers can be applied to a search term:
+Like the query above, this one would also select all Windows mochitest tasks. But it will
+additionally select:
+
+.. code-block:: text
+
+    test-macosx1014-64-shippable/opt-talos-sessionrestore-many-windows-e10s
+
+This is because both sequences of letters (``wndws`` and ``mchtst``) independently appear in order
+somewhere in this string (remember the order of the terms makes no difference).
+
+At first fuzzy terms may not seem very useful, but they are actually extremely powerful! Let's use
+the term from the interface image above, ``'linux64 mochibrochr``, as an example. First, just notice
+how in the image ``fzf`` highlights the characters that constitute the match in green. Next, notice
+how typing ``mochibrochr`` can quickly get us all mochitest browser-chrome tasks. The power of fuzzy
+terms is that you don't need to memorize the exact task labels you are looking for. Just start
+typing something you think is vaguely correct and chances are you'll see the task you're looking for.
+
+
+Term Modifiers
+~~~~~~~~~~~~~~
+
+The following modifiers can be applied to a search term:
 
 .. code-block:: text
 
@@ -66,7 +169,19 @@ For example:
 
 .. code-block:: text
 
-    ^start 'exact | !ignore fuzzy end$
+    ^start 'exact | 'other !ignore fuzzy end$
+
+would match the string:
+
+.. code-block:: text
+
+    starting to bake isn't exactly fun, but pizza is yummy in the end
+
+.. note::
+
+    The best way to learn how to write queries is to run ``mach try fuzzy --no-push`` and play
+    around with all of these modifiers!
+
 
 Specifying Queries on the Command Line
 --------------------------------------

tools/tryselect/mach_commands.py

@@ -215,33 +215,58 @@ def try_default(self, argv=None, **kwargs):
                 description='Select tasks on try using a fuzzy finder',
                 parser=get_parser('fuzzy'))
     def try_fuzzy(self, **kwargs):
-        """Select which tasks to use with fzf.
+        """Select which tasks to run with a fuzzy finding interface (fzf).
+
+        When entering the fzf interface you'll be confronted by two panes. The
+        one on the left contains every possible task you can schedule, the one
+        on the right contains the list of selected tasks. In other words, the
+        tasks that will be scheduled once you you press <enter>.
+
+        At first fzf will automatically select whichever task is under your
+        cursor, which simplifies the case when you are looking for a single
+        task. But normally you'll want to select many tasks. To accomplish
+        you'll generally start by typing a query in the search bar to filter
+        down the list of tasks (see Extended Search below). Then you'll either:
+
+        A) Move the cursor to each task you want and press <tab> to select it.
+        Notice it now shows up in the pane to the right.
+
+        OR
+
+        B) Press <ctrl-a> to select every task that matches your filter.
+
+        You can delete your query, type a new one and select further tasks as
+        many times as you like. Once you are happy with your selection, press
+        <enter> to push the selected tasks to try.
+
+        All selected task labels and their dependencies will be scheduled. This
+        means you can select a test task and its build will automatically be
+        filled in.
 
-        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>
+          Ctrl-K / Up    => Move cursor up
+          Ctrl-J / Down  => Move cursor down
+          Tab            => Select task + move cursor down
+          Shift-Tab      => Select task + move cursor up
+          Ctrl-A         => Select all currently filtered tasks
+          Ctrl-D         => De-select all currently filtered tasks
+          Ctrl-T         => Toggle select all currently filtered tasks
+          Alt-Bspace     => Clear query from input bar
+          Enter          => Accept selection and exit
+          Ctrl-C / Esc   => Cancel selection and exit
+          ?              => Toggle preview pane
 
         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.
 
+
         Extended Search
         ---------------
 
@@ -256,6 +281,13 @@ def try_fuzzy(self, **kwargs):
         For example:
 
           ^start 'exact | !ignore fuzzy end$
+
+
+        Documentation
+        -------------
+
+        For more detailed documentation, please see:
+        https://firefox-source-docs.mozilla.org/tools/try/selectors/fuzzy.html
         """
         if kwargs.pop('interactive'):
             kwargs['query'].append('INTERACTIVE')