|
@@ -1,5 +1,7 @@
|
|
|
-Writing good issue reports
|
|
|
-==========================
|
|
|
+Writing issue reports
|
|
|
+=====================
|
|
|
+
|
|
|
+### Bugs and features only
|
|
|
|
|
|
First things first: **the issue tracker is NOT for tech support**. It is for
|
|
|
reporting bugs and requesting features. If your issue amounts to "I can't get
|
|
@@ -7,9 +9,15 @@ YCM to work on my machine" and the reason why is obviously related to your
|
|
|
machine configuration and the problem would not be resolved with _reasonable_
|
|
|
changes to the YCM codebase, then the issue is likely to be closed.
|
|
|
|
|
|
+### Where to go for help
|
|
|
+
|
|
|
**A good place to ask questions is the [Gitter room][gitter] or the
|
|
|
[ycm-users][] Google group**. Rule of thumb: if you're not sure whether your
|
|
|
-problem is a real bug, ask on the room or the group.
|
|
|
+problem is a real bug, ask on the room or the group.
|
|
|
+
|
|
|
+Don't go to `#vim` on freenode for support. See the [readme][] for further help.
|
|
|
+
|
|
|
+### Installation problem - read the docs
|
|
|
|
|
|
**YCM compiles just fine**; [the build bots say so][build-bots]. If the bots are
|
|
|
green and YCM doesn't compile on your machine, then _your machine is the root
|
|
@@ -25,16 +33,42 @@ This leads us to point #2: **make sure you have checked the docs before
|
|
|
reporting an issue**. The docs are extensive and cover a ton of things; there's
|
|
|
also an FAQ at the bottom that quite possibly addresses your problem.
|
|
|
|
|
|
+For installation problems, make sure that any issue report includes the entire
|
|
|
+output of any build or installation commands, including **the command used to
|
|
|
+run them**.
|
|
|
+
|
|
|
+### Other problems - check the issue tracker
|
|
|
+
|
|
|
Further, **search the issue tracker for similar issues** before creating a new
|
|
|
one. There's no point in duplication; if an existing issue addresses your
|
|
|
-problem, please comment there instead of creating a duplicate.
|
|
|
+problem, please comment there instead of creating a duplicate. However, if the
|
|
|
+issue you found is **closed as resolved** (e.g. with a PR or the original user's
|
|
|
+problem was resolved), raise a **new issue**, because you've found a new
|
|
|
+problem. Reference the original issue if you think that's useful information.
|
|
|
+
|
|
|
+If you do find a similar open issue, **don't just post 'me too' or similar**
|
|
|
+responses. This almost never helps resolve the issue, and just causes noise for
|
|
|
+the maintainers. Only post if it will aid the maintainers in solving the issue;
|
|
|
+if there are existing diagnostics requested in the thread, perform
|
|
|
+them and post the results.
|
|
|
+
|
|
|
+When replying, follow the instructions for getting the required diagnostics for
|
|
|
+posting a new issue (see below), and add them to your response. This is likely
|
|
|
+to help the maintainers find a fix for you, rather than have them spend time
|
|
|
+requesting them again. To be clear, the maintainers *always* need the
|
|
|
+diagnostics (debug info, log files, versions, etc.) even for responses on
|
|
|
+existing issues.
|
|
|
|
|
|
You should also **search the archives of the [ycm-users][] mailing list**.
|
|
|
|
|
|
+### Check your YCM version
|
|
|
+
|
|
|
Lastly, **make sure you are running the latest version of YCM**. The issue you
|
|
|
have encountered may have already been fixed. **Don't forget to recompile
|
|
|
ycm_core.so too** (usually by just running `install.py` again).
|
|
|
|
|
|
+## Creating an issue
|
|
|
+
|
|
|
OK, so we've reached this far. You need to create an issue. First realize that
|
|
|
the time it takes to fix your issue is a multiple of how long it takes the
|
|
|
developer to reproduce it. The easier it is to reproduce, the quicker it'll be
|
|
@@ -42,10 +76,20 @@ fixed.
|
|
|
|
|
|
Here are the things you should do when creating an issue:
|
|
|
|
|
|
+1. Most importantly, **read and complete the issue template**. The maintainers
|
|
|
+ rely on the style and structure of the issue template to quickly resolve your
|
|
|
+ issue. If you don't complete it in full, then the maintainers may elect to
|
|
|
+ ignore or simply close your issue. This isn't personal, it's just that they
|
|
|
+ are busy too.
|
|
|
1. **Write a step-by-step procedure that when performed repeatedly reproduces
|
|
|
your issue.** If we can't reproduce the issue, then we can't fix it. It's
|
|
|
that simple.
|
|
|
-2. Add the output of [the `:YcmDebugInfo` command][ycm-debug-info-command].
|
|
|
+2. Explain **what you expected to happen**, and **what actually happened**.
|
|
|
+ This helps us understand if it is a bug, or just a misunderstanding of the
|
|
|
+ behavior.
|
|
|
+2. Add the output of [the `:YcmDebugInfo` command][ycm-debug-info-command]. Make
|
|
|
+ sure that when you run this, your cursor is in the file that is experiencing
|
|
|
+ the issue.
|
|
|
3. Put the following options in your vimrc:
|
|
|
```viml
|
|
|
let g:ycm_keep_logfiles = 1
|
|
@@ -109,8 +153,9 @@ Creating good pull requests
|
|
|
change is known. _What goal is your change trying to accomplish?_
|
|
|
|
|
|
|
|
|
-[build-bots]: https://travis-ci.org/Valloric/YouCompleteMe
|
|
|
+[build-bots]: https://dev.azure.com/YouCompleteMe/YCM/_build/latest?definitionId=1&branchName=master
|
|
|
[ycm-users]: https://groups.google.com/forum/?hl=en#!forum/ycm-users
|
|
|
[gitter]: https://gitter.im/Valloric/YouCompleteMe
|
|
|
-[ycm-debug-info-command]: https://github.com/Valloric/YouCompleteMe#the-ycmdebuginfo-command
|
|
|
-[ycm-toggle-logs-command]: https://github.com/Valloric/YouCompleteMe#the-ycmtogglelogs-command
|
|
|
+[readme]: https://github.com/ycm-core/YouCompleteMe
|
|
|
+[ycm-debug-info-command]: https://github.com/ycm-core/YouCompleteMe#the-ycmdebuginfo-command
|
|
|
+[ycm-toggle-logs-command]: https://github.com/ycm-core/YouCompleteMe#the-ycmtogglelogs-command
|