1 files changed, 152 insertions, 0 deletions
diff --git a/docs/contributing/debugging/stacktrace_report.rst b/docs/contributing/debugging/stacktrace_report.rst
new file mode 100644
index 0000000000..dfbfb714ca
--- /dev/null
+++ b/docs/contributing/debugging/stacktrace_report.rst
@@ -0,0 +1,152 @@
+How to get a stacktrace for a bug report
+========================================
+
+If you file a bug report in Bugzilla about a crash you should include a
+stacktrace (call stack) in your report. A stacktrace will tell Mozilla
+developers what crashed and provide a starting point for investigating
+its cause. This article describes how to use the Mozilla Crash Reporter
+(Breakpad) to get a crash ID, which our engineers can use to get a
+stacktrace, and alternative ways to get a stacktrace if you can't get a
+crash ID.
+
+Requirements
+------------
+
+You need a binary build of Firefox from
+`Mozilla.org <https://www.mozilla.org/firefox/>`__. SeaMonkey and
+Thunderbird also support crash reporting.
+
+Mozilla's crash report server currently only has debug information for
+Mozilla builds and thus the crash reporter cannot work if you use a
+build from a Linux distribution or if you compile from source code. In
+these cases you will need to use one of the :ref:`alternative
+methods <Alternative ways to get a stacktrace>` listed below.
+
+.. note::
+
+   **Note:** When filing a crash report, it is important to know whether
+   the crash occurs with `Firefox safe
+   mode <http://support.mozilla.com/kb/Safe+Mode>`__. This helps
+   engineers determine whether a particular
+   `extension <http://support.mozilla.com/kb/Troubleshooting+extensions+and+themes>`__
+   or
+   `plugin <http://support.mozilla.com/kb/Troubleshooting+plugins>`__
+   is the cause of the crash.
+
+
+How to get a crash ID with the Mozilla Crash Reporter
+-----------------------------------------------------
+
+1 - Crash and submit a report to the system.
+
+.. image:: img/reporter.jpg
+
+The Mozilla Crash Reporter window should automatically come up after Firefox crashes.
+If you have any additional information about the crash, such as additional detail on
+what you were doing at the time that may have triggered the crash, please enter it
+into the comments box. Be sure that you **check the "Tell Mozilla about this crash"**
+checkbox and click the restart button. The crash reporter should now submit the
+crash report and Firefox should open again.
+
+.. note::
+
+   The "Details" button gives additional data about the incident,
+   however this is not useful in a bug report.
+
+
+2 - Tell us the ID of the report you submitted.
+
+.. image:: img/crashlist.jpg
+
+To access all of your submitted reports type "about:crashes" into the Firefox address bar
+and press enter. Firefox should open a list of IDs for your submitted crash reports.
+Copy two or three of the IDs for the appropriate crashes and paste them into your
+Bugzilla report. Please check the listed times to avoid copying the ID of an unrelated
+crash report.
+
+.. note::
+
+   You can prefix a "bp-" to the beginning of an ID to make Bugzilla turn it
+   into a link: bp-a70759c6-1295-4160-aa30-bc4772090918
+
+
+How to get the crash ID if Firefox crashes on startup
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If Firefox crashes on startup you can still access your submitted crash
+reports. Crash reports are accessible from all Firefox profiles, so if a
+`new
+profile <https://support.mozilla.org/kb/profile-manager-create-remove-switch-firefox-profiles>`__
+does not crash you can use it to access them through "about:crashes" as above.
+
+
+Accessing crash report IDs outside of Firefox
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you cannot load Firefox at all you can find the crash report files at
+this location depending on your operating system:
+
+* Windows : ``%APPDATA%\Mozilla\Firefox\Crash Reports\submitted\``
+* macOS : ``~/Library/Application Support/Firefox/Crash Reports/submitted/``
+* Linux : ``~/.mozilla/firefox/Crash Reports/submitted/``
+
+Each file in this folder contains one submitted crash report ID. You can
+check the modified or creation time for each file to discern which crash
+reports are relevant to your bug report.
+
+
+Alternative ways to get a stacktrace
+------------------------------------
+
+If the Mozilla crash reporter doesn't come up or isn't available you
+will need to obtain a stacktrace manually:
+
+
+Windows
+~~~~~~~
+
+See the article :ref:`Create a stacktrace with Windbg` for information
+on how to do this.
+
+For a full process dump, see :ref:`How to get a process dump with Windows
+Task Manager`.
+
+
+macOS
+~~~~~
+
+Run /Applications/Utilities/Console.app.  Expand "~/Library/Logs" and
+"CrashReporter", then look for logs for "firefox-bin".
+
+
+Linux
+~~~~~
+
+Note that for most distros, the package you need to get symbols for will
+be something like "xulrunner", not "firefox".
+
+
+Crash reports files on your computer
+------------------------------------
+
+When Breakpad initially catches a crash it first writes crash report
+files (e.g. .dump and .extra files) into the 'pending' subdirectory of
+its 'Crash Reports' directory.
+
+If Breakpad successfully sends the crash report to the reporting server
+then, by default, the files added to the 'pending' subdirectory for the
+crash are removed, and a .txt file is placed in the 'submitted'
+directory containing the crash ID created by the reporting server.
+
+If you want Breakpad to leave the .dump and .extra files on your
+computer so that you can examine them locally, then set the
+MOZ_CRASHREPORTER_NO_DELETE_DUMP environment variable to 1.
+
+-  Ubuntu:  `Instructions from the Ubuntu
+   Team <https://wiki.ubuntu.com/MozillaTeam/Bugs#Obtain%20a%20backtrace%20from%20an%20apport%20crash%20report%20(using%20gdb)>`__
+-  openSUSE:  `General instructions from
+   openSUSE <https://en.opensuse.org/openSUSE:Bugreport_application_crashed>`__
+-  Fedora: `Capturing Stack
+   Traces <https://fedoraproject.org/wiki/StackTraces>`__
+-  Gentoo: `Debugging using
+   GDB <https://wiki.gentoo.org/wiki/Debugging_with_GDB>`__