From 17d7cbe315868e881431b837532d0aa8dc3080db Mon Sep 17 00:00:00 2001
From: Vadim Zeitlin <vadim@wxwidgets.org>
Date: Sun, 12 Nov 2023 21:13:02 +0100
Subject: [PATCH] Try to make bug report instructions even more clear

---
 .github/ISSUE_TEMPLATE/bug_report.md | 60 ++++++++++++++++++----------
 1 file changed, 39 insertions(+), 21 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index cb4eb30a8d..9194f7027d 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -11,29 +11,49 @@ assignees: ''
 IMPORTANT NOTE
 --------------
 
-Please note that this entry field uses [Markdown][1], which means that you
-need to escape any code snippets pasted here using fenced code blocks,
-i.e. by putting ``` before and after it. Also escape, using
-backslash, i.e. `\<` any angle brackets to prevent them from being
-interpreted as HTML tags.
+Please note that this entry field uses Markdown, see
 
-Use the Preview tab to review your issue before submitting it to verify that
-your formatting is correct.
+https://docs.github.com/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax
 
-[1]: https://docs.github.com/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax
+if you're unfamiliar with it, and make sure to use the "Preview" tab just above
+to review your issue before submitting it to verify that your formatting is
+correct.
 
----
+In particular, please use code blocks, i.e. put ``` on a separate line before
+and after any block of code or long text (such as compiler or make output).
+
+Also make sure to escape, using backslash, i.e. `\<`, any angle brackets
+to prevent them from being interpreted as HTML tags.
+
+Finally, feel free to remove the explanatory comments, including this one,
+after reading (and hopefully following) them.
+
+-->
+
+### Description
+<!--
+Please use the following sections in your report:
+
+#### Bug description:
 
-Describe the bug:
 A clear and concise description of what the bug is.
 
-Expected vs observed behaviour:
+#### Expected vs observed behaviour:
+
 Please describe what you expected to happen and what actually happens. Make
 sure to explain what exactly is the problem, just attaching a screenshot is
 not always sufficient. When in doubt, please provide more details rather
 than too few.
 
-Patch or snippet allowing to reproduce the problem:
+#### Stack trace:
+
+If relevant, i.e. if the problem is a crash or an assert failure, please run
+the program under debugger and copy and paste here (as text, not as an image:
+you can use Ctrl+C in MSVS "Stack" window) the stack shown when you break into
+the debugger once the problem happens.
+
+#### Patch or snippet allowing to reproduce the problem:
+
 Please attach the smallest possible patch allowing to reproduce the problem
 in a sample. If there is absolutely no appropriate sample, please attach a
 minimal self-contained example in a single file.
@@ -41,7 +61,8 @@ minimal self-contained example in a single file.
 Skip this step if the problem can be reproduced in one of the samples
 without any changes.
 
-To Reproduce:
+#### To Reproduce:
+
 Steps to reproduce the behaviour, please make them as detailed as possible.
 For example:
 
@@ -51,17 +72,14 @@ For example:
 4. See error
 -->
 
-### Description
-<!-- Describe the bug here -->
-
 
 ### Platform and version information
 
 - wxWidgets version <!-- [e.g. 3.2.1] --> you use:
 - wxWidgets port <!-- [e.g. wxMSW, wxGTK, wxOSX] --> you use:
 - OS <!-- [e.g. Windows 10, Ubuntu 22.10, macOS 15] --> and its version:
-
-<!-- For wxGTK only (**remove** this section if not using wxGTK) -->
-+ GTK version: <!-- [e.g. 3.24.5] -->
-+ Which GDK <!-- [X11 or Wayland] --> backend is used:
-+ Current theme: <!-- (If relevant, i.e. for appearance-related problems) -->
+  <!-- For wxGTK only (**remove** this section if not using wxGTK) -->
+  + GTK version: <!-- [e.g. 3.24.5] -->
+  + Which GDK <!-- [X11 or Wayland] --> backend is used:
+  + Desktop environment <!-- [e.g. Gnome or KDE] -->:
+  + Current theme: <!-- (If relevant, i.e. for appearance-related problems) -->