branch: externals/eglot
commit 2387026d67c68a33cab605bb4e3e64d9928918a3
Author: João Távora <joaotav...@gmail.com>
Commit: João Távora <joaotav...@gmail.com>
Tweak bug-reporting templates yet again
---
.github/ISSUE_TEMPLATE/bug_report.md | 139 +++++++++++++++++------------------
.github/ISSUE_TEMPLATE/config.yml | 4 +-
2 files changed, 71 insertions(+), 72 deletions(-)
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md
b/.github/ISSUE_TEMPLATE/bug_report.md
index 2829b6cb86..b11c614f81 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -1,35 +1,35 @@
---
-name: 🐞 Bug Report
-about: Something didn't function the way you expected it to
+name: Formal bug report
+about: Something didn't work right, and you've written a perfect MRE recipe
title: ''
labels: ''
assignees: ''
---
<!-- To continue, you will need to provide some elements
- including a description of a [MINIMUM REPRODUCIBLE EXAMPLE][1] (MRE). If
- you don't have that, DON'T CREATE AN BUG REPORT ISSUE.
-
- 👉 Need help configuring or understanding Emacs, Eglot, or LSP?
- Have an idea for a feature? Strongly sususpect there is an
- Eglot bug, but can't supply a MINIMUM REPRODUCIBLE EXAMPLE?
- Please DON'T OPEN A NEW BUG REPORT ISSUE!
-
- Head to https://github.com/joaotavora/eglot/discussions to
- discuss. Start a new discussion, there are no templates there,
- you can just speak your mind.
-
- 👉 Maybe your issue is already solved or worked around. Have glance at
-
https://github.com/joaotavora/eglot/issues?q=is%3Aissue+label%3Aworkaround
-
- 👉 You can also make an Emacs bug report, which can also be used
- for general discussion. You'll potentially reach more people
- this way. You can do it via `M-x report-emacs-bug` or just
- send email to `bug-gnu-em...@gnu.org`. Be sure to `CC:` (or
- better, `X-Debbugs-CC:` ) Eglot's maintainer, currently
- `joaotav...@gmail.com`.
-
- If you don't provide the needed elements, WE MAY CLOSE THE ISSUE
- JUST LIKE THAT 😐.
+including a description of a [MINIMUM REPRODUCIBLE EXAMPLE][1] (MRE). If
+you don't have that, DON'T CREATE AN BUG REPORT ISSUE.
+
+Need help configuring or understanding Emacs, Eglot, or LSP? Have an
+idea for a feature? Strongly suspect there is an Eglot bug, but can't
+supply a MINIMUM REPRODUCIBLE EXAMPLE? Please DON'T OPEN A NEW BUG
+REPORT ISSUE!
+
+Head to https://github.com/joaotavora/eglot/discussions to
+discuss. Start a new discussion, there are no templates there,
+you can just speak your mind.
+
+Maybe your issue is already solved or worked around. Have glance at
+https://github.com/joaotavora/eglot/issues?q=is%3Aissue+label%3Aworkaround
+
+You can also make an Emacs bug report, which can also be used
+for general discussion. You'll potentially reach more people
+this way. You can do it via `M-x report-emacs-bug` or just
+send email to `bug-gnu-em...@gnu.org`. Be sure to `CC:` (or
+better, `X-Debbugs-CC:` ) Eglot's maintainer, currently
+`joaotav...@gmail.com`.
+
+If you don't provide the needed elements, WE MAY CLOSE THE ISSUE
+JUST LIKE THAT.
-->
* Server used: <!-- (clangd, gopls, etc..) -->
@@ -42,12 +42,12 @@ assignees: ''
#### LSP transcript - M-x eglot-events-buffer (mandatory unless Emacs
inoperable)
<!-- DO NOT SKIP: Include the invaluable LSP transcript.
- Inside Emacs, you can display that buffer with the M-x
- eglot-events-buffer command. It contains the JSONRPC messages
- exchanged between client and server, as well as the messages the
- server prints to stderr. Copy that text and paste it below as a
- formatted code block
-
(https://help.github.com/articles/creating-and-highlighting-code-blocks/)). -->
+Inside Emacs, you can display that buffer with 'M-x
+eglot-events-buffer'. It contains the JSONRPC messages exchanged
+between client and server, as well as the messages the server prints
+to stderr. Copy that text and paste it below as a formatted code
+block
+(https://help.github.com/articles/creating-and-highlighting-code-blocks/)). -->
```lisp
... Paste the events transcript here ... Try to start from the line that says
@@ -58,10 +58,10 @@ assignees: ''
#### Backtrace (mandatory, unless no error message seen or heard):
<!-- DO NOT SKIP:
- If Emacs errored (you saw -- and possibly heard -- an error message),
- make sure you repeat the process after enabling backtraces with
- `M-x toggle-debug-on-error`. The backtrace buffer contains text that
- you should include here, again as a formatted code block.
+If Emacs errored (you saw -- and possibly heard -- an error message),
+make sure you repeat the process after enabling backtraces with
+`M-x toggle-debug-on-error`. The backtrace buffer contains text that
+you should include here, again as a formatted code block.
-->
```lisp
@@ -78,61 +78,60 @@ Debugger entered--Lisp error: (error "oh no")
#### Minimum Reproducible Example (mandatory)
<!-- DO NOT SKIP:
-
- You need to provide a MINIMAL, REPRODUCIBLE and COMPLETE recipe.
- This is the bit most trouble to some people. So please, I kindly
- ask that you read [this first][1] for a general idea of what is
- requested.
-
- You have to create a short guide to help us replicate the problem
- JUST AS IT HAPPENED TO YOU. Make sure to double check that
- following your own guide leads to the problem reliably.
+
+You need to provide a MINIMAL, REPRODUCIBLE and COMPLETE recipe.
+This is the bit that most troubles some people. So please, I
+kindly ask that you read [this first][1] for a general idea of
+what is requested.
+
+You HAVE to create a short guide to help us replicate the problem
+JUST AS IT HAPPENED TO YOU. Make sure to double check that
+following your own guide leads to the problem reliably.
-->
-Make sure to describe:
+Here's how I suggest you structure your recipe:
-1. How Emacs is started
+1. How is Emacs started?
-3. Where the language server executable lives in the machine and how
- it is installed
+3. Where does the language server executable live in your machine and
+ how should it be installed?
-4. What project files are needed to demonstrate the problem. Please
+4. What project files are needed to demonstrate the problem? Please
don't say "_just open any Zglorb source file_".
Don't assume the Eglot maintainers have any time to learn about a
- specific programming language and its associated toolchain. Attach
+ specific programming language and its associated toolchain. Attach
the actual file or files, or link to a repository containing them.
-5. How Emacs is operated/configured before you invoke Eglot
+5. How is Emacs operated/configured _before_ you invoke Eglot?
-6. How Emacs is operated after you invoke Eglot
+6. How is Emacs operated _after_ you invoke Eglot
-7. What actions must be taken for the problem to manifest itself
+7. What actions must be taken for the problem to manifest itself?
-8. What the expected behaviour is
+8. What is the expected behaviour?
-9. What the observed behaviour is
+9. What is the observed behaviour?
-10. IMPORTANT: Double check that doing steps 1-9 all over again by
- yourself leads to the error.
+10. VERY IMPORTANT: follow your own recipe (steps 1-9) by yourself
+ and verify that it leads to the error.
You don't HAVE to follow this guide if you are confident you can
describe your own [COMPLETE, MINIMAL and REPRODUCIBLE][1] recipe. See
https://github.com/joaotavora/eglot/issues/696 for a good example of
an issue following this template.
- <!-- THANK YOU!
+<!-- THANK YOU!
- Having a runnable reproduction not only "proves" your bug to us
- but also allows us to spend all our effort fixing the bug
- instead of struggling to understand your issue.
-
- If you find that building the MRE takes a lot of work, well,
- that may be so, but keep in mind that that work will have to be
- expended at least once to solve your problem, and it's often the
- most time-consuming task. So it pays if you can do that work
- upfront.
-
- Thank you very much. -->
+Having a runnable reproduction not only "proves" your bug to us
+but also allows us to spend all our effort fixing the bug
+instead of struggling to understand your issue.
+
+If you find that building the MRE takes a lot of work, well, that may
+be so :-) But keep in mind that that work will have to be expended at
+least once by someone to solve your problem, and it's often the most
+time-consuming task. So it pays if you can do that work upfront.
+
+Thank you very much. -->
[1]: https://stackoverflow.com/help/minimal-reproducible-example
diff --git a/.github/ISSUE_TEMPLATE/config.yml
b/.github/ISSUE_TEMPLATE/config.yml
index 02577de421..d6ff8d9113 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -1,8 +1,8 @@
blank_issues_enabled: false
contact_links:
- - name: "Discuss Eglot, request features, report bugs informally"
+ - name: "Report bugs informally, discuss Eglot, request features"
url: https://github.com/joaotavora/eglot/discussions
- about: Ask questions, request features, answer questions
+ about: Informally and freely report problems, ask questions, etc
- name: "Additional Support: Emacs Help"
url: https://lists.gnu.org/mailman/listinfo/help-gnu-emacs
about: Search, ask and answer questions
