Bug 1843636 - Update docs to explain the output of ./mach build and ./mach run. r=sylvestre DONTBUILD

This patch updates the quick reference doc as well as the detailed
build docs for each operating system. These updates should help new
contributors understand what is happening when initially setting up
their Firefox development environment.

There is also a new  "Build errors" section in each detailed build doc
to enable new contributors to get the help they need in debugging build
issues. The quick reference doc points out these new sections in the
"To build & run" heading.

Additionally this patch adds some more context to the OS specific build
doc links in the quick start reference doc.

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

docs/contributing/contribution_quickref.rst

@@ -34,7 +34,7 @@ Windows dependencies
 
     All the commands of this tutorial must be run in the shell provided with the MozillaBuild Package (start-shell.bat)
 
-:ref:`More information <Building Firefox On Windows>`
+:ref:`More information on building Firefox on Windows <Building Firefox On Windows>`
 
 Bootstrap a copy of the Firefox source code
 -------------------------------------------
@@ -58,7 +58,7 @@ To Setup Firefox On Windows
     $ wget https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py
     $ python3 bootstrap.py
 
-More information :ref:`for Windows <Building Firefox On Windows>`
+More information on :ref:`building Firefox for Windows <Building Firefox On Windows>`.
 
 To Setup Firefox On macOS and Linux
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -68,7 +68,7 @@ To Setup Firefox On macOS and Linux
     $ curl https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py -O
     $ python3 bootstrap.py
 
-More information :ref:`for Linux <Building Firefox On Linux>` and :ref:`for MacOS <Building Firefox On MacOS>`
+More information on :ref:`building Firefox for Linux <Building Firefox On Linux>` and :ref:`building Firefox for MacOS <Building Firefox On MacOS>`.
 
 To set up your editor
 ---------------------
@@ -111,7 +111,11 @@ To run it:
 
      $ ./mach run
 
-:ref:`More information about Linux <Building Firefox On Linux>` / :ref:`More information about MacOS <Building Firefox On MacOS>`
+This command will open your locally built Firefox in a new window.
+
+:ref:`More information about building Firefox on Linux <Building Firefox On Linux>` / :ref:`More information about building Firefox on MacOS <Building Firefox On MacOS>`
+
+If you encounter build errors, please reference the more detailed "Building Firefox" on your specific operating system document and specifically the "Troubleshooting" section.
 
 .. _write_a_patch:
 

docs/setup/linux_build.rst

@@ -124,9 +124,19 @@ Now that your system is bootstrapped, you should be able to build!
     cd mozilla-unified
     hg up -C central
     ./mach build
-    ./mach run
 
 🎉 Congratulations! You've built your own home-grown Firefox!
+You should see the following message in your terminal after a successful build:
+
+.. code-block:: console
+
+    Your build was successful!
+    To take your build for a test drive, run: |mach run|
+    For more information on what to do now, see https://firefox-source-docs.mozilla.org/setup/contributing_code.html
+
+You can now use the ``./mach run`` command to run your locally built Firefox!
+
+If your build fails, please reference the steps in the `Troubleshooting section <#troubleshooting>`_.
 
 Now the fun starts
 ------------------
@@ -141,6 +151,14 @@ send patches to Mozilla, update your source code locally, and more.
 Troubleshooting
 ---------------
 
+Build errors
+~~~~~~~~~~~~
+
+If you encounter a build error when trying to setup your development environment, please follow these steps:
+   1. Copy the entire build error to your clipboard
+   2. Paste this error to `paste.mozilla.org <https://paste.mozilla.org>`_ in the text area and change the "Expire in one hour" option to "Expire in one week". Note: it won't take a week to get help but it's better to have the snippet be around for a bit longer than expected.
+   3. Go to the `introduction channel <https://chat.mozilla.org/#/room/#introduction:mozilla.org>`__ and ask for help with your build error. Make sure to post the link to the paste.mozilla.org snippet you created!
+
 Using a non-native file system (NTFS, network drive, etc)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/setup/macos_build.rst

@@ -104,9 +104,19 @@ Now that your system is bootstrapped, you should be able to build!
     cd mozilla-unified
     hg up -C central
     ./mach build
-    ./mach run
 
 🎉 Congratulations! You've built your own home-grown Firefox!
+You should see the following message in your terminal after a successful build:
+
+.. code-block:: console
+
+    Your build was successful!
+    To take your build for a test drive, run: |mach run|
+    For more information on what to do now, see https://firefox-source-docs.mozilla.org/setup/contributing_code.html
+
+You can now use the ``./mach run`` command to run your locally built Firefox!
+
+If your build fails, please reference the steps in the `Troubleshooting section <#troubleshooting>`_.
 
 Now the fun starts
 ------------------
@@ -117,3 +127,14 @@ say hello in the `Introduction channel
 start working on <https://codetribute.mozilla.org/>`_.
 See the :ref:`Firefox Contributors' Quick Reference` to learn how to test your changes,
 send patches to Mozilla, update your source code locally, and more.
+
+Troubleshooting
+---------------
+
+Build errors
+~~~~~~~~~~~~
+
+If you encounter a build error when trying to setup your development environment, please follow these steps:
+   1. Copy the entire build error to your clipboard
+   2. Paste this error to `paste.mozilla.org <https://paste.mozilla.org>`_ in the text area and change the "Expire in one hour" option to "Expire in one week". Note: it won't take a week to get help but it's better to have the snippet be around for a bit longer than expected.
+   3. Go to the `introduction channel <https://chat.mozilla.org/#/room/#introduction:mozilla.org>`__ and ask for help with your build error. Make sure to post the link to the paste.mozilla.org snippet you created!

docs/setup/windows_build.rst

@@ -1,5 +1,5 @@
 Building Firefox On Windows
-===========================
+======================================
 
 This document will help you get set up to build Firefox on your own
 computer. Getting set up can take a while - we need to download a
@@ -104,10 +104,12 @@ Microsoft Defender Antivirus manually
 
 .. note::
 
-    If you're already missing files (you'll see them listed in ``hg status``, you can have them
-    brought back by reverting your source tree: ``hg update -C``).
+    If you are using Mercurial and you're already missing files (you'll see them listed in ``hg status``), you can have them
+    brought back by reverting your source tree: ``hg update -C``.
 
-3. Build
+    If you are using Git and you're already missing files (you'll see them listed in ``git status``), you can have them brought back by discarding changes in your source tree: ``git restore .``.
+
+1. Build
 --------
 
 Now that your system is bootstrapped, you should be able to build!
@@ -117,9 +119,19 @@ Now that your system is bootstrapped, you should be able to build!
     cd c:/mozilla-source/mozilla-unified
     hg up -C central
     ./mach build
-    ./mach run
 
 🎉 Congratulations! You've built your own home-grown Firefox!
+You should see the following message in your terminal after a successful build:
+
+.. code-block:: console
+
+    Your build was successful!
+    To take your build for a test drive, run: |mach run|
+    For more information on what to do now, see https://firefox-source-docs.mozilla.org/setup/contributing_code.html
+
+You can now use the ``./mach run`` command to run your locally built Firefox!
+
+If your build fails, please reference the steps in the `Troubleshooting section <#troubleshooting>`_.
 
 Now the fun starts
 ------------------
@@ -140,6 +152,14 @@ send patches to Mozilla, update your source code locally, and more.
 Troubleshooting
 ---------------
 
+Build errors
+~~~~~~~~~~~~
+
+If you encounter a build error when trying to setup your development environment, please follow these steps:
+   1. Copy the entire build error to your clipboard
+   2. Paste this error on `paste.mozilla.org <https://paste.mozilla.org>`_ in the text area and change the "Expire in one hour" option to "Expire in one week". Note: it won't take a week to get help but it's better to have the snippet be around for a bit longer than expected.
+   3. Go to the `introduction channel <https://chat.mozilla.org/#/room/#introduction:mozilla.org>`__ and ask for help with your build error. Make sure to post the link to the paste.mozilla.org snippet you created!
+
 MozillaBuild out-of-date
 ~~~~~~~~~~~~~~~~~~~~~~~~