CONTRIBUTING

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 contributors.  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.