YouCompleteMe/CONTRIBUTING.md

76 lines
3.9 KiB
Markdown
Raw Normal View History

2013-04-03 21:50:01 -04:00
Writing good issue reports
==========================
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
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.
Realize that quite literally _thousands_ of people have gotten YCM to work
successfully so if you can't, it's probably because you have a peculiar
system/Vim configuration or you didn't go through the docs carefully enough.
It's very unlikely to be caused by an actual bug in YCM because someone would
have already found it and reported it.
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.
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.
Lastly, **make sure you are running the latest version of YCM**. The issue you
have encountered may have already been fixed.
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
fixed.
2013-04-03 21:50:01 -04:00
Here are the things you should do when creating an issue:
1. **Write a step-by-step sequence of steps that repeatedly reproduce your
issue.** If we can't reproduce the issue, then we can't fix it. It's that
simple.
2. **Create a test case for your issue**. This is critical. Don't talk about how
"when I have X in my file" or similar, _create a file with X in it_ and put
the contents inside code blocks in your issue description. Try to make this
test file _as small as possible_. Don't just paste a huge, 500 line source
file you were editing and present that as a test. _Minimize_ the file so that
the problem is reproduced with the smallest possible amount of test data.
3. **Include your OS and OS version.**
4. **Include the output of `vim --version`.**
Creating good pull requests
===========================
1. **Follow the code style of the existing codebase.**
- The Python code **DOES NOT** follow PEP 8. This is not an oversight, this
is by choice. You can dislike this as much as you want, but you still need
to follow the existing style. Look at other Python files to see what the
style is.
- The C++ code has an automated formatter (`style_format.sh` that runs
`astyle`) but it's not perfect. Again, look at the other C++ files and
match the code style you see.
- Same thing for VimScript. Match the style of the existing code.
2. **Explain in detail why your pull request makes sense.** Ask yourself, would
this feature be helpful to others? Not just a few people, but a lot of YCMs
users? See, good features are useful to many. If your feature is only useful
to you and _maybe_ a couple of others, then thats not a good feature.
There is such a thing as “feature overload”. When software accumulates so
many features of which most are only useful to a handful, then that software
has become “bloated”. We dont want that.
Requests for features that are obscure or are helpful to but a few, or are
not part of YCM's "vision" will be rejected. Yes, even if you provide a
patch that completely implements it.
Please include details on exactly what you would like to see, and why. The
why is important - it's not always clear why a feature is really useful. And
sometimes what you want can be done in a different way if the reason for the
change is known. _What goal are you trying to accomplish?_