Bug 1397433 - [tryselect] Create in-tree documentation for |mach try|, r=jmaher

This adds some basic documentation for |mach try| and its various subcommands.
This was a bit hastily made for the Austin all-hands, but at least provides a
place to link to and can be improved upon in the future.

MozReview-Commit-ID: 8N6LZO5kTlL

--HG--
extra : rebase_source : c7e215703426f6cfb03b044d188a53d1ba878a75

tools/moz.build

@@ -48,6 +48,7 @@ with Files("update-packaging/**"):
 
 SPHINX_TREES['lint'] = 'lint/docs'
 SPHINX_TREES['compare-locales'] = 'compare-locales/docs'
+SPHINX_TREES['try'] = 'tryselect/docs'
 
 CRAMTEST_MANIFESTS += [
     'tryselect/test/cram.ini',

tools/tryselect/docs/configuration.rst

@@ -0,0 +1,58 @@
+Configuring Try
+===============
+
+
+Getting Level 1 Commit Access
+-----------------------------
+
+In order to push to try, `Level 1 Commit Access`_ is required. Please see `Becoming a Mozilla
+Committer`_ for more information on how to obtain this.
+
+
+Configuring Version Control
+---------------------------
+
+After you have level 1 access, you'll need to do a little bit of setup before you can push. Both
+``hg`` and ``git`` are supported, move on to the appropriate section below.
+
+
+Configuring Try with Mercurial
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The recommended way to push to try is via the ``mach try`` command. This requires the
+``push-to-try`` extension which can be installed by running:
+
+.. code-block:: shell
+
+    $ mach mercurial-setup
+
+You should also enable the ``firefoxtree`` extension which will provide a handy ``try`` path alias.
+You can also create this alias manually by adding
+
+.. code-block:: ini
+
+    [paths] try = ssh://hg.mozilla.org/try
+
+This is only necessary if not using ``firefoxtree``.
+
+
+Configuring Try with Git Cinnabar
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The recommended way to use try with git is with `git cinnabar`_. You can follow `this tutorial`_ for
+a workflow which includes setting up the ability to push to try.
+
+
+Configuring Try with Vanilla Git
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This workflow isn't well supported, but is possible using `moz-git-tools`_, and specifically the
+`git push-to-try`_ command.
+
+
+.. _Level 1 Commit Access: https://www.mozilla.org/en-US/about/governance/policies/commit/access-policy/
+.. _Becoming a Mozilla Committer: https://www.mozilla.org/en-US/about/governance/policies/commit/
+.. _git cinnabar: https://github.com/glandium/git-cinnabar/
+.. _this tutorial: https://github.com/glandium/git-cinnabar/wiki/Mozilla:-A-git-workflow-for-Gecko-development
+.. _moz-git-tools: https://github.com/mozilla/moz-git-tools
+.. _git push-to-try: https://github.com/mozilla/moz-git-tools#git-push-to-try

tools/tryselect/docs/index.rst

@@ -0,0 +1,63 @@
+Try Server
+==========
+
+Try server, usually just referred to as try, is the easiest way to test a change without actually
+checking anything into a core repository. The change will undergo the same kinds of builds and tests
+as if it had landed on a regular integration branch, but will not get merged with mozilla-central.
+
+Try is just another mercurial repository (like inbound, autoland or mozilla-central) with a few key
+differences:
+
+    1. Pushing new heads is allowed.
+    2. It is non-publishing.
+
+The first point means that you'll never need to pull and rebase before pushing, each push creates a
+new head. In fact, the ability to push from old changesets is a very valuable property of try which
+is often used for things like regression hunting.
+
+The second point means that draft changesets (changesets that only exist in your local repository),
+will remain in the draft state after pushing.  Normally when pushing to an integration branch, a
+changeset gets marked 'public'. This ensures changes that are shared with others don't accidentally
+get mutated.  Pushing to try doesn't actually share the changeset with anyone, so changesets remain
+in the 'draft' state and they are still ok to mutate.
+
+.. rubric:: Using Try
+
+Before you can push to try, you'll need to have the proper credentials and do some light setup. See
+the :doc:`configuration` page for more information.
+
+The recommended way to push to try is via the ``mach try`` command. This will work with mercurial
+(via the ``push-to-try`` extension) and git (via ``git-cinnabar``). The ``mach try`` command offers
+a variety of different ``selectors`` which are implemented as a subcommands. See :doc:`selectors
+<selectors/index>` for available list.
+
+If no subcommand is specified, ``mach try`` will a subcommand to dispatch to. By default this is
+the ``syntax`` selector. In other words, these commands are equivalent:
+
+.. code-block:: shell
+
+    $ mach try
+    $ mach try syntax
+
+You can choose to use a different default selector by configuring your ``~/.mozbuild/machrc`` file:
+
+.. code-block:: ini
+
+    [try]
+    default=fuzzy
+
+
+.. toctree::
+  :caption: Table of Contents
+  :maxdepth: 2
+
+  configuration
+  selectors/index
+
+
+.. rubric:: Indices and tables
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

tools/tryselect/docs/selectors/empty.rst

@@ -0,0 +1,22 @@
+Empty Selector
+==============
+
+The ``mach try empty`` subcommand is very simple, it won't schedule any additional tasks. You'll
+still see lint tasks and python-unittest tasks if applicable, this is due to a configuration option
+in taskcluster.
+
+Other than those, your try run will be empty. You can use treeherder's ``Add new jobs`` feature to
+selectively add additional tasks after the fact.
+
+.. note::
+
+    To use ``Add new jobs`` you'll need to be logged in and have commit access level 1, just as if
+    you were pushing to try.
+
+To do this:
+
+    1. Click the drop-down arrow at the top right of your commit.
+    2. Select ``Add new jobs`` (it may take a couple seconds to load).
+    3. Choose your desired tasks by clicking them one at a time.
+    4. At the top of your commit, select ``Trigger New Jobs``.
+

tools/tryselect/docs/selectors/fuzzy.rst

@@ -0,0 +1,100 @@
+Fuzzy Selector
+==============
+
+The fuzzy selector uses a tool called `fzf`_. It allows you to filter down all of the task labels
+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.
+
+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:
+
+.. code-block:: text
+
+    Ctrl-K / Down  => Move cursor up
+    Ctrl-J / Up    => 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
+    ?              => 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/try>`.
+
+Extended Search
+---------------
+
+When typing in search terms, you can separate terms by spaces. These terms will be joined by the AND
+operator. For example the query:
+
+.. code-block:: text
+
+    windows mochitest
+
+Will match tasks that have both the terms ``windows`` AND ``mochitest`` in them. This is a fuzzy match so the query:
+
+.. code-block:: text
+
+    wndws mchtst
+
+Would likely match a similar set of tasks. The following modifiers can be applied to a search term:
+
+.. code-block:: text
+
+    'word    => exact match (line must contain the literal string "word")
+    ^word    => exact prefix match (line must start with literal "word")
+    word$    => exact suffix match (line must end with literal "word")
+    !word    => exact negation match (line must not contain literal "word")
+    'a | 'b  => OR operator (joins two exact match operators together)
+
+For example:
+
+.. code-block:: text
+
+    ^start 'exact | !ignore fuzzy end$
+
+Additional Arguments
+--------------------
+
+There are a few additional command line arguments you may wish to use:
+
+``-q/--query``
+Instead of opening the interactive interface, automatically apply the specified
+query. This is equivalent to opening the interface then typing: ``<query><ctrl-a><enter>``.
+
+``--full``
+By default, only target tasks (e.g tasks that would normally run on mozilla-central)
+are generated. Passing in ``--full`` allows you to select from all tasks. This is useful for
+things like nightly or release tasks.
+
+``-u/--update``
+Update the bootstrapped fzf binary to the latest version.
+
+For a full list of command line arguments, run:
+
+.. code-block:: shell
+
+    $ mach try fuzzy --help
+
+For more information on using ``fzf``, run:
+
+.. code-block:: shell
+
+    $ man fzf
+
+.. _fzf: https://github.com/junegunn/fzf

tools/tryselect/docs/selectors/index.rst

@@ -0,0 +1,32 @@
+Selectors
+=========
+
+These are the currently implemented try selectors:
+
+* :doc:`fuzzy <fuzzy>`: Select tasks using a fuzzy finding algorithm and
+  a terminal interface.
+* :doc:`empty <empty>`: Don't select any tasks. Taskcluster will still run
+  some tasks automatically (like lint and python unittest tasks). Further tasks
+  can be chosen with treeherder's ``Add New Jobs`` feature.
+* :doc:`syntax <syntax>`: Select tasks using classic try syntax.
+
+You can run them with:
+
+.. code-block:: shell
+
+    $ mach try <selector>
+
+See selector specific options by running:
+
+.. code-block:: shell
+
+    $ mach try <selector> --help
+
+.. toctree::
+  :caption: Available Selectors
+  :maxdepth: 1
+  :hidden:
+
+  Fuzzy <fuzzy>
+  Empty <empty>
+  Syntax <syntax>

tools/tryselect/docs/selectors/syntax.rst

@@ -0,0 +1,50 @@
+Syntax Selector
+===============
+
+.. warning::
+
+    Try syntax is antiquated and hard to understand. If you aren't already
+    familiar with try syntax, you might want to use the ``fuzzy`` selector
+    instead.
+
+Try syntax is a command line string that goes into the commit message. Using
+``mach try syntax`` will automatically create a temporary commit with your
+chosen syntax and then delete it again after pushing to try.
+
+Try syntax can contain all kinds of different options parsed by various
+places in various repos, but the majority are parsed by `try_option_syntax.py`_.
+The most common arguments include:
+
+    * ``-b/--build`` - One of ``d``, ``o`` or ``do``. This is the build type,
+      either opt, debug or both (required).
+    * ``-p/--platform`` - The platforms you want to build and/or run tests on
+      (required).
+    * ``-u/--unittests`` - The test tasks you want to run (optional).
+    * ``-t/--talos`` - The talos tasks you want to run (optional).
+
+Here are some examples:
+
+.. code-block:: shell
+
+    $ mach try syntax -b do -p linux,macosx64 -u mochitest-e10s-1,crashtest -t none
+    $ mach try syntax -b d -p win64 -u all
+    $ mach try syntax -b o -p linux64
+
+Unfortunately, knowing the magic strings that make it work can be a bit of a
+guessing game. If you are unsure of what string will get your task to run, try
+using :doc:`mach try fuzzy <fuzzy>` instead.
+
+While using ``mach try syntax -b do -p all -u all -t all`` will work, heavy use
+of ``all`` is discouraged as it consumes a lot of unnecessary resources (some of
+which are hardware constrained).
+
+Trychooser
+~~~~~~~~~~
+
+Commonly the `trychooser`_ web page is used to help build a try syntax, though
+it isn't always kept up to date. Check the boxes for the tasks you wish to run
+then copy/paste the computed ``mach try`` command into your terminal.
+
+
+.. _try_option_syntax.py: https://hg.mozilla.org/mozilla-central/file/tip/taskcluster/taskgraph/try_option_syntax.py
+.. _trychooser: https://mozilla-releng.net/trychooser/