vim/YouCompleteMe
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Update contributing guide

Browse Source 
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
This commit is contained in:
Ben Jackson 2019-06-29 09:27:53 +01:00 committed by GitHub
parent afd11447ae
commit 5c2032a64d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 53 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
CONTRIBUTING.md
View File

@ -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,10 +9,16 @@ 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.
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
cause_. Now read the first paragraph again.
@ -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