From 5c2032a64dec27d87bd3f94f732a671435453845 Mon Sep 17 00:00:00 2001 From: Ben Jackson Date: Sat, 29 Jun 2019 09:27:53 +0100 Subject: [PATCH] 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 --- CONTRIBUTING.md | 61 ++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 53 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e88c1e33..c2f46cf1 100644 --- a/CONTRIBUTING.md +++ b/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 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