branch: externals/eglot
commit fc221c8b8af33363a6a8d1e07950dc01555f6c9b
Author: João Távora <joaotav...@gmail.com>
Commit: João Távora <joaotav...@gmail.com>
Overhaul bug reporting template
Just stress some points slightly more so that people actually follow
the instructions.
---
.github/ISSUE_TEMPLATE/bug_report.md | 111 +++++++++++++++++++++--------------
1 file changed, 67 insertions(+), 44 deletions(-)
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md
b/.github/ISSUE_TEMPLATE/bug_report.md
index 346bd02..9df438b 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -5,19 +5,20 @@ title: ''
labels: ''
assignees: ''
---
-
<!-- Hello there, prospective issue reporter! Your bug reports are
very valuable 💛. They really are, and Eglot couldn't be made
without them. But there are lots of bugs and so little time. So
- please - do not - remove or skip parts of this template.
+
+ PLEASE - DO NOT - REMOVE OR SKIP PARTS OF THIS TEMPLATE.
- 👉🏽 Need help or tech support? Have an idea for a feature?
- Please don't open an issue!
+ 👉🏽 Need help configuring or understanding Emacs, Eglot, or LSP?
+ Have an idea for a feature? Please DON'T OPEN A NEW ISSUE!
* Head to https://github.com/joaotavora/eglot/discussions to
- discuss. Maybe that idea is already being discussed there.
+ discuss. Start a new discussion, there are no templates there,
+ you can say whatever you want.
- * Better yet, make an Emacs bug report, which can also be used
+ * 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
@@ -25,21 +26,26 @@ assignees: ''
`joaotav...@gmail.com`.
To make an issue, you need to provide some elements, which aren't
- hard to find. Unfortunately, if you don't provide these
- elements, ** we may close the issue just like that 😐 **. -->
+ hard to find. Can't find all the elements for this template?
+ No problem, just make a discussion 👆.
-[ ] Server used: <!-- (clangd, gopls, etc..) -->
-[ ] Emacs version: <!-- Type M-x emacs-version -->
-[ ] Eglot version: <!-- Look in M-x list-packages or tell Git SHA
-->
-[ ] Eglot installation method: <!--
Git/package.el/straight/use-package/don't know -->
-[ ] Using Doom: <!-- Yes/No -->
+ If you don't provide the needed elements, WE MAY CLOSE THE ISSUE
+ JUST LIKE THAT 😐 . -->
+
+* Server used: <!-- (clangd, gopls, etc..) -->
+* Emacs version: <!-- Type M-x emacs-version -->
+* Operating system: <!-- (windows/mac osx/linux/don't know -->
+* Eglot version: <!-- Look in M-x list-packages or tell Git SHA -->
+* Eglot installation method: <!--
Git/package.el/straight/use-package/don't know -->
+* Using Doom: <!-- Yes/No -->
-#### LSP transcript (mandatory, unless Emacs inoperable)
-<!-- Include the invaluable **events transcript**. 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
+#### LSP transcript - M-x eglot-events-buffer (mandatory unless Emacs
inoperable)
+<!-- DO NOT SKIP OR REMOVE: 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/)). -->
```lisp
@@ -49,14 +55,14 @@ assignees: ''
```
#### Backtrace (mandatory, unless no error message seen or heard):
-<!-- 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 also include here, again as
- a formatted code block. -->
+<!-- DO NOT SKIP OR REMOVE: 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 also include here,
+ again as a formatted code block. -->
```lisp
-... Paste the backtrace if you have it here ...
+... Paste the backtrace here ...
Debugger entered--Lisp error: (error "oh no")
signal(error ("oh no"))
error("oh no")
@@ -68,36 +74,53 @@ Debugger entered--Lisp error: (error "oh no")
```
#### Minimal configuration (mandatory)
-<!-- Are you using Doom Emacs or Spacemacs Emacs or some very special
- pimped-out Emacs? That's fine, but for this report we need you
- to replicate the problem with **as clean an Emacs run as
- possible**.
+<!-- DO NOT SKIP OR REMOVE: Are you using Doom Emacs or Spacemacs
+ Emacs or some very special pimped-out Emacs? That's fine, but
+ for this report we need to be able to replicate the problem JUST
+ AS IT HAPPENED TO YOU. We can't replicate your complex
+ configuration and environment, so you need to provide a MINIMAL,
+ REPRODUCIBLE and COMPLETE recipe.
- Some people submit whole Git repositories with a sandboxed
- configuration. That's fine, but sometimes simply Git-cloning the
- Eglot repo somewhere to your hard drive and a running this from
- the shell is more than enough: -->
+ How to do this? Here's the easiest way provided you can use the
+ shell in your system:-->
```sh
- /path/to/a/certain/version/of/emacs -Q -f package-initialize -L
/path/to/git-cloned/eglot -l eglot.el
+ # Type this in a shell to start an Emacs with Eglot configured
+ $ /path/to/a/certain/version/of/emacs -Q -f package-initialize -L
/path/to/git-cloned/eglot -l eglot.el
```
- <!-- You can then add some lines of setup like: -->
-
```lisp
+ ;; Example of a minimal init.el configuration
+ ;;
(add-to-list 'eglot-server-programs '(foo-mode "foo-server"))
(setq eglot-special-option-2000 '(foo bar with the airplane))
(some-clearly-identified-third-party-package)
- ;; Add some clear descriptions of M-x commands executed executed
- ;; If your bug relies of the contents of files such as
- ;; .dir-locals.el or some project file with some specific content
- ;; also do include their contents in separate code blocks.
- ```
+ ```
+
+ <!-- WHEW!!
- <!-- For some bugs it this may seem like overkill but believe us,
+ For some bugs, all this may seem like overkill but believe us,
very often what seems like a "clear issue" is actually specific
to some details of your setup. 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. (this well-worded paragraph taken from Rollup's bug
- tracker, BTW)-->
+ your issue.
+
+ Anyway, after you've launched Emacs + Eglot that please explain
+ what options you clicked on or what commands you entered, in a
+ way that is clear to the Eglot maintainers so they can replicate
+ the problem JUST AS IT HAPPENED TO YOU.
+
+ If this requires some bits of .emacs or init.el configuration,
+ you need to add them (just as in the example above)
+
+ If reproducing your error requires others files and or programs,
+ you NEED TO ADD snippets for them or provide links to them.
+
+ Some users also provide whole Git repositories perfectly
+ "sandboxing" a configuration and setup. If you're confident on
+ how do to this, that also works.
+
+ Thank you very much.
+
+ (Adapted this template from RollupJS's bug tracker). -->
