Skip to content

Commit

Permalink
Tweak bug-reporting templates yet again
Browse files Browse the repository at this point in the history
  • Loading branch information
@joaotavora
joaotavora committed Jul 24, 2022
1 parent 29690e8 commit 2387026
Show file tree
Hide file tree
Showing 2 changed files with 71 additions and 72 deletions.
139 changes: 69 additions & 70 deletions .github/ISSUE_TEMPLATE/bug_report.md
View file
Original file line number Diff line number Diff line change
@@ -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 `[email protected]`. Be sure to `CC:` (or
better, `X-Debbugs-CC:` ) Eglot's maintainer, currently
`[email protected]`.
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 `[email protected]`. Be sure to `CC:` (or
better, `X-Debbugs-CC:` ) Eglot's maintainer, currently
`[email protected]`.
If you don't provide the needed elements, WE MAY CLOSE THE ISSUE
JUST LIKE THAT.
-->
* Server used: <!-- (clangd, gopls, etc..) -->
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
4 changes: 2 additions & 2 deletions .github/ISSUE_TEMPLATE/config.yml
View file
Original file line number Diff line number Diff line change
@@ -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
Expand Down

0 comments on commit 2387026

Please sign in to comment.