For a person or company who wishes to submit a change to the IPFire distribution, this process can sometimes be daunting if you are not familiar with how this works. This page tried to give some useful suggestions about the DOs and DON'Ts. If you stick to them this will greatly increase the chances of your changes being accepted.
Please read carefully through this page and those that is referred to and follow the guidelines as closely as possible.
All changes to the IPFire distribution occur in the form of patches as generated by the diff command. For working with the source code we use Git and so you need, too. It is important that you send in patches in the unified diff format as it is generated by git diff and that the right headers are included. This makes work much easier for the developers and helps to track all changes in the most easy and accurate manner.
Here is how this works:
Step 1: Obtaining the sources
At first you need to obtain the sources of IPFire or the package that you want to modify. Please head over here to do that: Source Code
Step 2: Creating a development branch
You will need to create a new development branch for the changes you are going to make.
Make sure that you have configured Git correctly: Initial Git Setup
Step 3: Making your changes
Make your changes to the source code. This can be what ever you want. Patches that fix bugs and those which make the user-interface more clear are always welcome. Before you start working on bigger features that you want to see included in the IPFire distribution, please get in touch and discuss if it makes actually sense to include this and if there is a chance that the feature will actually be accepted.
Apart from that, please note the following advice:
Separate your changes
Separate each logical change into a separate patch.
For example, if your changes include both bug fixes and performance enhancements, separate those changes into two or more patches. On the other hand, if you make a single change to numerous files, group those together into a single patch. Thus a single logical change is contained within a single patch.
The point to remember is that each patch should make an easily understood change that can be verified by reviewers. Each patch should be justifiable on its own merits.
If one patch depends on another patch in order for a change to be complete, that is OK. Simply note "this patch depends on patch X" in your patch description.
When dividing your change into a series of patches, take special care to ensure that the whole builds process runs properly after each patch in the series. Developers using "git bisect" to track down a problem can end up splitting your patch series at any point; they will not thank you if you introduce bugs in the middle.
Style-check your changes
Check your patch for basic style violations. Failure to do so simply wasted the reviewers time and will get your patch rejected, probably without even being read.
Note that we do not have Coding Style guidelines for each and every language that we use in IPFire. Please use the code that you are modifying or enhancing for orientation.
Step 4: Commit your changes
Commit your changes in small steps which will create individual patches which can be reviewed easier. This is very important if you want your patch accepted.
Please also follow these guidelines for commits and use tags.
Step 5: Send your changes for review
Send your patches to the developers using email and Patchwork. Do not attach them to bugs on Bugzilla. Reviewers need to be able to comment on patches.
You may either send the patches manually -- for example, via a Mail User Agent. If you decide to do so take care to follow the guidelines below. You may also use git send-email or send a Git pull request which is the recommended way for very large patch sets.
git-send-email requires an extra package.
On Debian/Ubuntu/Fedora:
apt-get install git-email
FIXME Add how to use In-Reply-To and [PATCH v2]
Select the recipients for your patch
You should always copy the appropriate maintainer(s) on any patch to code that they maintain. You will find those in the makefiles of all packages in IPFire 3. You should also include at least one Development Mailing Lists to receive a copy of your patch set. development@lists.ipfire.org functions as a last resort. Do not spam any unrelated lists, though.
Do not send more than 15 patches at once to the mailing lists.
If you have a patch that fixes an exploitable security bug, send that patch to security@ipfire.org. For severe bugs, a short embargo may be considered to allow to get the patch out to users; in such cases, obviously, the patch should not be sent to any public lists.
No MIME, no links, no compression, no attachments. Just. Plain. Text.
The developers need to be able to read and comment on the changes you are submitting. It is important for them to be able to "quote" your changes, using standard email tools, so that they may comment on specific portions of your code.
For this reason, all patches should be submitting email "inline". WARNING: Be wary of your editor's word-wrap corrupting your patch, if you choose to cut-n-paste your patch.
Do not attach the patch as a MIME attachment, compressed or not.
Email size
Large changes are not appropriate for mailing lists. If your patch exceeds a couple of hundred kilobytes in size, it is preferred that you store your patch on an Internet-accessible server, and provide instead a URL pointing to your patch. But note that if your patch is that large, it almost certainly needs to be broken up anyway.
Respond to review comments
Your patch will almost certainly get comments from reviewers on ways in which the patch can be improved. You must respond to those comments; ignoring reviewers is a good way to get ignored in return.
Be sure to tell the reviewers what changes you are making and to thank them for their time. Code review is a tiring and time-consuming process, and reviewers sometimes get grumpy. Even in that case, though, respond politely and address the problems they have pointed out.
Never go private with a reviewer to discuss something further. This is of interest for everyone. Conversations that are taken off list look like they have been abandoned which will result in them being ignored.
Don't get discouraged - or impatient
After you have submitted your change, be patient and wait. Reviewers are busy people and may not get to your patch right away.
Once upon a time, patches used to disappear into the void without comment, but the development process works more smoothly than that now. You should receive comments within a week or so; if that does not happen, make sure that you have sent your patches to the right place. Wait for a minimum of one week before resubmitting or pinging reviewers - possibly longer during busy times like merge windows.
Include PATCH in the subject
Due to high email traffic to the maintainers and mailing lists, it is common convention to prefix your subject line with [PATCH]. This lets the reviewers more easily distinguish patches from other email discussions. This is added automatically when using git send-email.