diff --git a/CONTRIBUTING b/CONTRIBUTING new file mode 100644 index 000000000..87d014444 --- /dev/null +++ b/CONTRIBUTING @@ -0,0 +1,114 @@ +Important things to consider if you want to contribute to the project (or any +project in general, programming language and programming style aside) + +On authors, maintainers, and contributing: + + - If you want to write in a nice new contribution/feature, that's awesome, and + I fully encourage it. However, unless what you make is very easy to + maintain, do not submit a feature or module for distribution with the main + project if you don't plan on supporting it or maintaining it yourself. This + is *especially* important if it's big. Smaller features and contributions + that are simple to understand/maintain can get away with this, but + generally, other people do not want to have to fix your code if something + breaks. + + I completely understand that you may have a busy life outside of the + project, but if what you submit can go wrong, it will go wrong. If you + don't have time to fix major problems, then you probably shouldn't be + contributing to the project (or any project) in the first place. + + - Be prepared to work with other contibutors. If you are venturing in to + someone else's code (to improve/expand upon it, or to change it for the + better), be prepared to talk and work with that person, whomever it may be. + Do *not* go rewriting someone elses code from scratch just because you feel + you can do it better, Instead, examine what they did, talk with the person + (constructively) and if possible work with them to try to improve their + existing code. + + This may require you to have some level of people skills. That *doesn't* + mean you should have to take someone else's bullshit if they're being an + asshole or being completely unreasonable, but it does mean that you should + be somewhat civil and try to work together. + + - Be prepared to work with testers/users, sometimes you *have* to talk to + users and go over the problem and find the solution. Users don't always + know what they're doing, but I've found that most are more than willing to + be patient and follow your instructions to help you debug the problem for + mutual benefit. They will sing praises of you for fixing their problems, + and you will have one less problem to deal with. You'll find that the + community is awesome and filled with some amazing people. Work with them, + cherish them, because they are truly what make the wheels of your project + spin. For that reason, do *not* treat users badly, ever. + + - The author(s)/maintainer(s) often get the last say on big/important + decisions for the project as a whole. A good maintainer will always listen, + and will often ask others on the project for their opinions. At the same + time, don't always expect everything to be democratic. Each individual + project has its own rules, but more often than not it's probably more like a + benevolent dictatorship. If that is the case and you have an opinion about + a particular upcoming change/decision, simply talk with the maintainers + about your opinion, and unless it ventures too far outside of whatever + 'project vision' they have, they usually are (and should be) more than + willing to take your personal opinions in to account for the sake of the + project as a whole. + + Just keep in mind that there are always many subjective topics, and that + like anything that's subjective, there often will be differing opinions that + may not always become resolved. + + - However, that being said, do try to avoid taking up too much of the + maintainer's time on any given discussion. Try to be to be as concise as + possible, as they're often pretty busy, especially if they are doing most of + the work on the project (which is almost always the case). + +Styles, formatting, and guidelines for code + + - You may use C, C++. or Objective-C (for apple) to create your modules, + though please try to use C unless an API you're using requires C++ or + Objective-C (such as windows COM classes, or apple Objetive-C APIs). Some + maintainers may be lax with this (such as myself), but unless you plan on + always being there to maintain the code, it's generally best to use C so + everybody has common ground to work with. Language is a very personal thing + and not everyone will agree, but it's something that is ultimately the + decision of the author(s)/maintainer(s). Arguing about language in this + instance will only seek to annoy them. + + - Coding style is mostly KNF (linux-style). We're using KNF because it's an + established, well known style with the purpose of reducing bugs and + improving readability in a variety of circumstances. This means K&R, 80 + columns max, preferable maximum function length of 42 lines, 8 character + width tabs, lower_case_names, etc. I chose this for the sake of the + project, don't argue about it, don't talk to me about it, just do it. If + you can't deal with it, then you probably shouldn't be contributing to any + projects period, because every good project has coding guidelines. + + See https://www.kernel.org/doc/Documentation/CodingStyle for a general + guideline (though not necessarily a rulebook, for example we allow the use + of boolean return values instead of ints for failure). + + - C++ is an exception to the lower_case_only rule, CamelCase is encouraged + (though not required) to distinguish it from C code. Just a personal and + subjective stylistic thing on my part. + + - Do not use dependencies for the sake of convenience. Use them only if you + actually have a real need to depend on them. Just because the user + interface code depends on some toolkit doesn't mean it's okay for your + module to use that toolkit just so you can use some class or template they + have that you enjoy using. Use the standard language libraries and use + what's available in the core. + + - Core is C only (unless there's an operating specific thing that requires + another language). I will especially not accept any code in the core that + does not abide by these rules. I will be particularly uptight about the + core. + +About these guidelines + + - These guidelines, the coding style, the format are for the sake of the + project and everyone who contributes and helps maintain the project. They + are not done so much for the sake of myself as the maintainer, but for the + sake of everyone. These guidelines helps ensure better code, better + conitribution, better cooperation, and code that (hopefully) everyone can + contribute to on some measure of even ground. Everyone has their own + personal style but sometimes there just has to be common ground for the sake + of the project as a whole.