Browse Source

Update contributing guide

Along with a few minor changes:

- Make a note about "me too" posts and what to do if you do find similar issues
- Re-iterate the 3 pieces required for a bug report
- Break the text into sections
Ben Jackson 5 years ago
parent
commit
5c2032a64d
1 changed files with 53 additions and 8 deletions
  1. 53 8
      CONTRIBUTING.md

+ 53 - 8
CONTRIBUTING.md

@@ -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
 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
 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_
 machine configuration and the problem would not be resolved with _reasonable_
 changes to the YCM codebase, then the issue is likely to be closed.
 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
 **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
 [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
 **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
 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
 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.
 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
 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
 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**.
 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
 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
 have encountered may have already been fixed. **Don't forget to recompile
 ycm_core.so too** (usually by just running `install.py` again).
 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
 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
 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
 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:
 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
 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
    your issue.** If we can't reproduce the issue, then we can't fix it. It's
    that simple.
    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:
 3. Put the following options in your vimrc:
    ```viml
    ```viml
    let g:ycm_keep_logfiles = 1
    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?_
     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
 [ycm-users]: https://groups.google.com/forum/?hl=en#!forum/ycm-users
 [gitter]: https://gitter.im/Valloric/YouCompleteMe
 [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