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