Updated bug report template

.github/ISSUE_TEMPLATE/bug.yml

@@ -1,77 +1,119 @@
 name: Bug Report
-description: Report a bug
+description: Something is not working? Report a bug in Material for MkDocs.
+
 body:
-  - type: checkboxes
-    attributes:
-      label: Contribution guidelines
-      description: Please read the contribution guidelines before proceeding.
-      options:
-        - label: I've read the [contribution guidelines](https://github.com/squidfunk/mkdocs-material/blob/master/CONTRIBUTING.md) and wholeheartedly agree
-          required: true
-  - type: checkboxes
-    attributes:
-      label: I've found a bug and checked that ...
-      description: Make sure that your request fulfills all of the following requirements. If one requirement cannot be satisfied, explain in detail why.
-      options:
-      - label: ... the problem doesn't occur with the `mkdocs` or `readthedocs` themes
-        required: true
-      - label: ... the problem persists when all overrides are removed, i.e. `custom_dir`, `extra_javascript` and `extra_css`
-      - label: ... the documentation does not mention anything about my problem
-      - label: ... there are no open or closed issues that are related to my problem
   - type: textarea
+    id: context
     attributes:
-      label: Description
+      label: Context
-      description: Please provide a brief description of the bug in 1-2 sentences.
+      description: >-
+        This field is optional. You may provide additional context for the bug
+        you want to report, helping us to understand what you are working on and
+        what you are trying to achieve. If the context is not relevant, you can
+        leave this field empty. [More](https://squidfunk.github.io/mkdocs-material/bug-report/#context)
+    validations:
+      required: false
+
+  - type: textarea
+    id: bug-description
+    attributes:
+      label: Bug description
+      description: >-
+        Please give a detailed description of the bug. Explain where Material
+        for MkDocs does not behave as you would expect it to. Be as specific as
+        possible. If you have found a workaround or a fix for the problem,
+        please let us maintainers (and all other users) know. [More](https://squidfunk.github.io/mkdocs-material/bug-report/#bug-description)
     validations:
       required: true
+
   - type: textarea
+    id: related-links
     attributes:
-      label: Expected behaviour
+      label: Related links
-      description: Please describe precisely what you'd expect to happen.
+      description: >-
+        Please list all links to the sections of
+        [our documentation](https://squidfunk.github.io/mkdocs-material) that
+        are relevant to the bug, in order to show that you have consulted and
+        thoroughly read it. Additionally, list links to possibly related issues
+        or discussions you encountered when searching our issue tracker.
+        [More](https://squidfunk.github.io/mkdocs-material/bug-report/#related-links)
+      value: |-
+        - [Bug reporting](https://squidfunk.github.io/mkdocs-material/bug-report/)
+        -
     validations:
       required: true
+
   - type: textarea
+    id: reproduction
     attributes:
-      label: Actual behaviour
+      label: Reproduction
-      description: Please describe precisely what is actually happening.
+      description: >-
+        Please create a __minimal reproduction__ for the bug. First, read our
+        [reproduction guide](https://squidfunk.github.io/mkdocs-material/bug-report/reproduction/)
+        that explains the necessary steps, then use the [built-in info plugin](https://squidfunk.github.io/mkdocs-material/bug-report/reproduction/#built-in-info-plugin) (mandatory) to create a self-contained
+        .zip file with the reproduction. Without a reproduction, it can be
+        challenging to fix the bug. [More](https://squidfunk.github.io/mkdocs-material/bug-report/#reproduction)
+      placeholder: |-
+        Drag and drop .zip file with reproduction here.
     validations:
       required: true
+
   - type: textarea
+    id: steps-to-reproduce
     attributes:
       label: Steps to reproduce
-      description: Please describe the steps to reproduce the bug.
+      description: >-
+        Please provide a detailed list of instructions, guiding us maintainers
+        through the required steps, helping us to recreate the problem using the
+        minimal reproduction you provided. Be as specific as possible and as
+        verbose as necessary – try not to leave anything out. [More](https://squidfunk.github.io/mkdocs-material/bug-report/reproduction/#steps-to-reproduce)
       placeholder: |-
         1. ...
         2. ...
         3. ...
     validations:
       required: true
-  - type: textarea
+
+  - type: dropdown
+    id: browser
     attributes:
-      label: Package versions
+      label: Browser
-      description: Please provide all package versions, i.e. run the commands in backticks on a shell.
+      description: >-
-      value: |-
+        If the bug only happens in __specific browsers__, please select them
-        - Python: `python --version`
+        from the dropdown below. If your browser is not listed or the version
-        - MkDocs: `mkdocs --version`
+        is relevant, you may select _Other_ and provide more details in the
-        - Material: `pip show mkdocs-material | grep -E ^Version`
+        field above this field. [More](https://squidfunk.github.io/mkdocs-material/bug-report/reproduction/#browser)
-    validations:
+      multiple: true
-      required: true
+      options:
-  - type: textarea
+        - Chrome
+        - Safari
+        - Edge
+        - Firefox
+        - Opera
+        - Other
+
+  - type: checkboxes
+    id: checklist
     attributes:
-      label: Configuration
+      label: Before submitting
-      description: Please provide a minimal (!) `mkdocs.yml` to reproduce the bug.
+      description: >-
-      placeholder: |-
+        Please ensure your bug report fulfills all of the following requirements.
-        site_name: My Docs
+        If you are not sure what a specific requirement means, follow the link
-        site_url: https://example.com/docs
+        to learn about it and understand why it is necessary before ticking the
-      render: yaml
+        box. This will save the maintainers and you valuable time.
-    validations:
+      options:
+        - label: >-
+            I have read and followed the [bug reporting guidelines](https://squidfunk.github.io/mkdocs-material/bug-report/).
           required: true
-  - type: textarea
+        - label: >-
-    attributes:
+            I have attached links to [the documentation](https://squidfunk.github.io/mkdocs-material),
-      label: System information
+            and possibly related [issues](https://github.com/squidfunk/mkdocs-material/issues)
-      description: Please provide your operating system and browser type and version.
+            or [discussions](https://github.com/squidfunk/mkdocs-material/discussions).
-      value: |-
+          required: true
-        - Operating system: ...
+        - label: >-
-        - Browser: ...
+            I assure that I have [removed all customizations](https://squidfunk.github.io/mkdocs-material/bug-report/#remove-customizations)
-    validations:
+            before submitting this bug report.
+          required: true
+        - label: >-
+            I have attached a [minimal reproduction](https://squidfunk.github.io/mkdocs-material/bug-report/reproduction/).
           required: true