diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml index 6dcba90b2..9c5ae71d6 100644 --- a/.github/ISSUE_TEMPLATE/bug.yml +++ b/.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 - description: Please provide a brief description of the bug in 1-2 sentences. + label: Context + 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 - description: Please describe precisely what you'd expect to happen. + label: Related links + 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 - description: Please describe precisely what is actually happening. + label: Reproduction + 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 - description: Please provide all package versions, i.e. run the commands in backticks on a shell. - value: |- - - Python: `python --version` - - MkDocs: `mkdocs --version` - - Material: `pip show mkdocs-material | grep -E ^Version` - validations: - required: true - - type: textarea + label: Browser + description: >- + If the bug only happens in __specific browsers__, please select them + from the dropdown below. If your browser is not listed or the version + is relevant, you may select _Other_ and provide more details in the + field above this field. [More](https://squidfunk.github.io/mkdocs-material/bug-report/reproduction/#browser) + multiple: true + options: + - Chrome + - Safari + - Edge + - Firefox + - Opera + - Other + + - type: checkboxes + id: checklist attributes: - label: Configuration - description: Please provide a minimal (!) `mkdocs.yml` to reproduce the bug. - placeholder: |- - site_name: My Docs - site_url: https://example.com/docs - render: yaml - validations: - required: true - - type: textarea - attributes: - label: System information - description: Please provide your operating system and browser type and version. - value: |- - - Operating system: ... - - Browser: ... - validations: - required: true + label: Before submitting + description: >- + Please ensure your bug report fulfills all of the following requirements. + If you are not sure what a specific requirement means, follow the link + to learn about it and understand why it is necessary before ticking the + box. This will save the maintainers and you valuable time. + options: + - label: >- + I have read and followed the [bug reporting guidelines](https://squidfunk.github.io/mkdocs-material/bug-report/). + required: true + - label: >- + I have attached links to [the documentation](https://squidfunk.github.io/mkdocs-material), + and possibly related [issues](https://github.com/squidfunk/mkdocs-material/issues) + or [discussions](https://github.com/squidfunk/mkdocs-material/discussions). + required: true + - label: >- + I assure that I have [removed all customizations](https://squidfunk.github.io/mkdocs-material/bug-report/#remove-customizations) + 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