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.
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, religion, or sexual identity and orientation.
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 like git 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, then split it. - Get your commit messages and/or patch descriptions right. See below.
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.
Please make sure to adhere to the coding style of the project you are modifying.
We understand that our (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
to fix/improve.
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 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.