Your changes and contributions to these projects are very welcome.
To make sure that your changes can be merged into the project as quickly as possible and with the minimal amount of work on both sides, a few rules should be adhered to.
There are several ways to contribute your source code to any project on this website. It basically boils down to any of these:
- Either send changes as patches in Unified Diff format via E-Mail to the maintainer. Diffs can be created using the diff utility using the diff -u command line switch. Also most source code management tools or tools like quilt can be used to generate diffs.
- Or send a pull request from your git repository via E-Mail.
- Or use Github and send a git pull request via Github.
All these ways are equally fine. However, it is extremely important to
get your patches/changes into a committable shape before submission.
That means you'll have to:
- Split your changes into logical units ready for commit/merge.
It is not OK to have one big commit that adds a feature, fixes
a bug and brings world peace all in one single changeset.
Split these (in this example) into (at least!) 3 patches/changes with meaningful
commit messages for each of them.
If you are unsure whether to split a certain patch, split it.
- Get your commit messages and/or patch descriptions right. See below.
Please make sure to adhere to the coding style of the project you are modifying. For example for most projects that means use tabs instead of spaces for code indentation.
I understand that my (or any other) particular coding style might not be your favorite style. However, it is important to keep the coding style within one project consistent. No matter what the actual style is. Just don't switch between styles within one code base, please.
Please try to create a good description for all of your changes
which describes why you did the change and what it is trying
Be as verbose as possible.
A commit message or patch description formally consists of the following parts:
- A short description, which describes the change in one single line.
This is the first line. It might look like this:
squizzler: Pimp the squizzler to do squazzling, too.
Here 'squizzler:' is the name of the subsystem or part of the software that you are modifying.
- A blank line follows.
- A verbose description of the change follows. This may be omitted, if
the first line described the change good enough already. However, if you
want to convince me to apply your patch, you'd better have a verbose
and meaningful description message. ;)
In the verbose part of the message describe why you did the change among more technical details.
Please always substantiate your changes. You need to explain in detail why you think a certain change is needed. Convince the maintainer of your excellent work.
Providing supporting data will help you to do so. For example:
- Profile the code, if you are making speed/efficiency improvements. A profile report saying that the code got 50 % faster is way better than a vague guess. And everything that is not measured is a vague guess.
- If you reverse engineered a hardware protocol, let everybody see the wire protocol dumps that you made. This way your actual implementation of the protocol will be much clearer and can be checked.
We want to create high quality Free Software.
Most projects are beyond the state of being bad hacks. There are real users depending on this software in their daily work. We don't want to cause tears. So we need to keep our quality standards as high as possible.