From 0fd45397c1d5a252dca4d2be793e5a1bf189a74a Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Fri, 14 Oct 2022 15:56:41 +0100
Subject: [PATCH] Simplify bug report template

---
 .github/ISSUE_TEMPLATE/bug-report.yml | 80 ++++++++++++---------------
 1 file changed, 34 insertions(+), 46 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml
index c78f1a2a730..9eeac53aba9 100644
--- a/.github/ISSUE_TEMPLATE/bug-report.yml
+++ b/.github/ISSUE_TEMPLATE/bug-report.yml
@@ -7,16 +7,34 @@ body:
     attributes:
       label: Describe the bug
       description: >-
-        A clear and concise description of what the bug is.
+        A clear and concise description of what the bug is, including the 
+        expected behaviour and what has gone wrong.
+        
+        Please include screenshots, if applicable.
     validations:
       required: true
 
   - type: textarea
     attributes:
       label: How to Reproduce
-      description: Please provide steps to reproduce this bug.
+      description: >-
+        Please provide steps to reproduce this bug, with the smallest possible
+        set of source files. For normal bugs this should ideally be one 
+        ``index.rst`` file, and for ``sphinx.ext.autodoc`` bugs, this should
+        ideally be a single ``index.rst`` file, and a single example Python 
+        module.
       value: |
+        Minimal method (you can also paste the contents of ``index.rst`` and
+        ``conf.py`` into this report):
+        ```bash
+        $ echo "Content demonstrating the bug..." > index.rst
+        $ echo "" > conf.py
+        $ sphinx-build -M html . _build
+        $ # open _build/html/index and see bla bla
         ```
+        
+        ``git clone`` method (this is advised against, to help the Sphinx team):
+        ```bash
         $ git clone https://github.com/.../some_project
         $ cd some_project
         $ pip install -r requirements.txt
@@ -27,28 +45,6 @@ body:
     validations:
       required: true
 
-  - type: textarea
-    attributes:
-      label: Expected behavior
-      description: >-
-        A clear and concise description of what you expected to happen.
-
-  - type: input
-    attributes:
-      label: Your project
-      description: >-
-        Link to your sphinx project, or attach zipped small project sample.
-    validations:
-      required: true
-
-  - type: textarea
-    attributes:
-      label: Screenshots
-      description: >-
-        If applicable, add screenshots to help explain your problem.
-    validations:
-      required: false
-
   - type: markdown
     attributes:
       value: |
@@ -56,38 +52,30 @@ body:
 
   - type: input
     attributes:
-      label: OS
+      label: Environment Information
       description: >-
-        [e.g. Unix/Linux/Mac/Win/other with version]
-    validations:
-      required: true
-  - type: input
-    attributes:
-      label: Python version
-    validations:
-      required: true
-  - type: input
-    attributes:
-      label: Sphinx version
+        Install development Sphinx 
+        ``pip install https://github.com/AA-Turner/sphinx/archive/refs/heads/5.x.zip``
+        then run ``sphinx-build --bug-report`` or ``python -m sphinx --bug-report``.
+        and paste the output here.
     validations:
       required: true
   - type: input
     attributes:
       label: Sphinx extensions
       description: >-
-        [e.g. sphinx.ext.autodoc, recommonmark]
-    validations:
-      required: false
-  - type: input
-    attributes:
-      label: Extra tools
-      description: >-
-        [e.g. Browser, tex or something else]
+        Attempt to reproduce your error with the smallest set of extensions possible.
+        This makes it easier to determine where the problem you are encountering is.
+        
+        e.g. ["sphinx.ext.autodoc", "recommonmark"]
     validations:
       required: false
   - type: textarea
     attributes:
       label: Additional context
       description: >-
-        Add any other context about the problem here.
-        [e.g. URL or Ticket]
+        Add any other context about the problem here, for example:
+        
+        * Any other tools used (Browser, TeX, etc) with versions
+        * Reference to another issue or pull request
+        * URL to some external resource