diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index c6f6aa835ac8..f94424a87555 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.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. + -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** -A clear and concise description of what the bug is. +## Reproduce -**To Reproduce** -Steps 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. + -**Screenshots** -If applicable, add screenshots to help explain your problem. +## Expected behavior -**Desktop (please complete the following information):** + -- 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. + -If available, please include the following details: +- Operating System and version: +- Browser and version: +- JupyterLab version:
Troubleshoot Output 
@@ -53,6 +53,6 @@ Paste the output from your command line running `jupyter lab` here, use `--debug
 
 
Browser Output
 
-Paste the output from your browser console here.
+Paste the output from your browser Javascript console here.
 

 

diff --git a/.github/ISSUE_TEMPLATE/installation-and-configuration-issues.md b/.github/ISSUE_TEMPLATE/installation-and-configuration-issues.md
deleted file mode 100644
index 32344a5a56fe..000000000000
--- a/.github/ISSUE_TEMPLATE/installation-and-configuration-issues.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-name: Installation and configuration issues
-about: Installation and configuration assistance
----
-
-If you are having issues with installation or configuration, we encourage you to post in the [Jupyter Discourse forum](https://discourse.jupyter.org/c/jupyterlab) or file an issue here.
diff --git a/docs/source/getting_started/faq.rst b/docs/source/getting_started/faq.rst
index 0f84f18ff366..9d410ce7c84b 100644
--- a/docs/source/getting_started/faq.rst
+++ b/docs/source/getting_started/faq.rst
@@ -11,13 +11,14 @@ General
 -  :ref:`Is JupyterLab ready to use? `
 -  :ref:`What will happen to the classic Jupyter Notebook? `
 -  `Where is the official online documentation for
-   JupyterLab? `__
+   JupyterLab? `__
+-  :ref:`How can you report a bug or issue? `
+
 
 Development
 -----------
 
--  `How can you report a bug or provide
-   feedback? `__
+  
 -  `How can you
    contribute? `__
 -  :ref:`How can you extend or customize JupyterLab? `
diff --git a/docs/source/getting_started/issue.rst b/docs/source/getting_started/issue.rst
new file mode 100644
index 000000000000..2430273e2c40
--- /dev/null
+++ b/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 `__, 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 `__. 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 `__.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index fc5e3e52a768..9739c6eda498 100644
--- a/docs/source/index.rst
+++ b/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