Add docs to help users diagnose issues before creating them

.github/ISSUE_TEMPLATE/bug_report.md

@@ -3,40 +3,40 @@ name: Bug report
 about: Create a report to help us improve
 ---
 
-Hi! Thanks for using JupyterLab.
+<!--
+Welcome! Before creating a new issue:
+* Search for relevant issues
+* Follow the issue reporting guidelines:
+https://jupyterlab.readthedocs.io/en/latest/getting_started/issue.html
+-->
 
-If you are reporting an issue with JupyterLab, please use the [GitHub issue](https://github.com/jupyterlab/jupyterlab/issues) search feature to check if your issue has been asked already. If it has, please add your comments to the existing issue.
+## Description
 
-The JupyterLab team and Project Jupyter value our community, and JupyterLab
-follows the Jupyter [Community Guides](https://jupyter.readthedocs.io/en/latest/community/content-community.html).
+<!--Describe the bug clearly and concisely. Include screenshots if possible-->
 
-**Describe the bug**
-A clear and concise description of what the bug is.
+## Reproduce
 
-**To Reproduce**
-Steps to reproduce the behavior:
+<!--Describe step-by-step instructions to reproduce the behavior-->
 
 1. Go to '...'
-2. Click on '....'
-3. Scroll down to '....'
-4. See error
+2. Click on '...'
+3. Scroll down to '...'
+4. See error '...'
 
-**Expected behavior**
-A clear and concise description of what you expected to happen.
+<!--Describe how you diagnosed the issue. See the guidelines at
+ https://jupyterlab.readthedocs.io/en/latest/getting_started/issue.html -->
 
-**Screenshots**
-If applicable, add screenshots to help explain your problem.
+## Expected behavior
 
-**Desktop (please complete the following information):**
+<!--Describe what you expected to happen-->
 
-- OS: [e.g. Windows 10]
-- Browser [e.g. chrome 69.0, firefox 62.0]
-- JupyterLab [e.g. 0.34.2]
+## Context
 
-**Additional context**
-Add any other context about the problem here.
+<!--Complete the following for context, and add any other relevant context-->
 
-If available, please include the following details:
+- Operating System and version:
+- Browser and version:
+- JupyterLab version:
 
 <details><summary>Troubleshoot Output</summary>
 <pre>
@@ -53,6 +53,6 @@ Paste the output from your command line running `jupyter lab` here, use `--debug
 
 <details><summary>Browser Output</summary>
 <pre>
-Paste the output from your browser console here.
+Paste the output from your browser Javascript console here.
 </pre>
 </details>

docs/source/getting_started/faq.rst

@@ -11,13 +11,14 @@ General
 -  :ref:`Is JupyterLab ready to use? <releases>`
 -  :ref:`What will happen to the classic Jupyter Notebook? <releases>`
 -  `Where is the official online documentation for
-   JupyterLab? <https://jupyterlab.readthedocs.io/en/stable/>`__
+   JupyterLab? <https://jupyterlab.readthedocs.io>`__
+-  :ref:`How can you report a bug or issue? <issue>`
+
 
 Development
 -----------
 
--  `How can you report a bug or provide
-   feedback? <https://github.com/jupyterlab/jupyterlab/issues>`__
+
 -  `How can you
    contribute? <https://github.com/jupyterlab/jupyterlab/blob/master/CONTRIBUTING.md>`__
 -  :ref:`How can you extend or customize JupyterLab? <user_extensions>`

docs/source/getting_started/issue.rst

@@ -0,0 +1,70 @@
+.. _issue:
+
+Reporting an issue
+------------------
+
+Thank you for providing feedback about JupyterLab.
+
+Diagnosing an Issue
+~~~~~~~~~~~~~~~~~~~
+
+If you find a problem in JupyterLab, please follow the steps below to diagnose and report the issue. Following these steps helps you diagnose if the problem is likely from JupyterLab or from a different project.
+
+1. Try to reproduce the issue in a new environment with the latest official JupyterLab installed and no extra packages. 
+
+   If you are using conda:
+
+     1. create a new environment::
+
+         conda create -n jlab-test --override-channels --strict-channel-priority -c conda-forge -c anaconda jupyterlab
+
+     2. Activate the environment::
+
+         conda activate jlab-test
+
+     3. Start JupyterLab::
+
+         jupyter lab
+
+   - I cannot reproduce this issue in a clean environment: The problem is probably not in JupyterLab itself. Go to step 2.
+   - I can reproduce this issue in a clean environment: Go to step 3.
+2. Perhaps the issue is in one of the JupyterLab extensions you had installed. Install any JupyterLab extensions you had one at a time, checking for the issue after each one.
+
+   - I can reproduce the issue after installing a particular extension: That extension may be causing the problem. File an issue with that extension's issue tracker. Be sure to mention what you have done here to narrow the problem down.
+   - I cannot reproduce the issue after installing all my extensions: Good news! Likely all you have to do is update your JupyterLab and extensions. If that fixes the issue, great! If it doesn't fix the issue, you may have a more complicated issue. Go directly to :ref:`create-issue`.
+3. Try to reproduce the issue in the classic Jupyter Notebook. Launch the classic notebook from the JupyterLab help menu to ensure you are getting exactly the same notebook server that JupyterLab is using.
+
+   - I can reproduce the issue with the classic Jupyter Notebook: The problem is probably not from JupyterLab. It may be in the `Jupyter Notebook server <https://github.com/jupyter/notebook>`__, your kernel, etc. Use your best judgement to file an issue with the appropriate project.
+   - I cannot reproduce the issue in classic Jupyter Notebook: Go to step 4.
+4. Try to reproduce the issue in your browser incognito or private browsing modeq. Running in private browser mode ensures your browser state is clean.
+
+   - I cannot reproduce the issue in private browsing mode: Perhaps resetting your cookies or other browser state would help.
+   - I can reproduce the issue in private browsing mode: Go to :ref:`create-issue`.
+
+You might also check your system for:
+
+- Security software that might be preventing access to files or network interfaces
+- Network equipment, routers, or proxies that might be preventing communication between the browser and the server
+- Browser extensions that might be changing the JupyterLab code or application page
+
+.. _create-issue:
+
+Creating an issue
+~~~~~~~~~~~~~~~~~
+
+Before creating an issue, search in the issue tracker for relevant issues. If you find an issue describing your problem, comment there with the following information instead of creating a new issue. If you find a relevant resolved issue (closed and locked for discussion), create a new issue and reference the resolved issue.
+
+To create an issue, collect the following contextual information:
+
+- relevant package versions, including:
+
+  - ``jupyterlab`` and ``notebook`` versions
+  - browser versions affected (please try to reproduce in Chrome and Firefox at least)
+  - operating system and version
+
+- relevant server and JavaScript error messages
+- screenshots or short screencasts illustrating the issue
+
+`Create a new issue <https://github.com/jupyterlab/jupyterlab/issues/new>`__. Include the contextual information from above. Describe how you followed the diagnosis steps above to conclude this was a JupyterLab issue.
+
+Communication in JupyterLab follows the Jupyter `Community Guides <https://jupyter.readthedocs.io/en/latest/community/content-community.html>`__.

docs/source/index.rst

@@ -21,6 +21,7 @@ JupyterLab is the next-generation web-based user interface for Project Jupyter.
    getting_started/overview
    getting_started/installation
    getting_started/starting
+   getting_started/issue
    getting_started/faq
    getting_started/changelog