Preparing patches for submission
MadWifi is a project that is driven by volunteers, and every contribution is appreciated. In addition, submitting patches that fix bugs or add new features is a good start to get used to the driver even when you don't have write access to the code repository (yet).
We ask you to stick to the following conventions when contributing code to MadWifi, in order to make the process as easy and time-saving as possible for everyone involved:
- Follow the coding style that is used throughout the rest of the source (which is the same coding style used for the Linux kernel - read more). Most important:
- Indent with tabs, not with spaces
- Use spaces after if, and start a new line after the condition
- Use in-source comments where necessary, so that thirds understand what your code does. Don't add comments like "modified by xyz" to mark your changes, such information generally is managed by Subversion (and will be visible in the commit log).
- Always send your changes as diffs. Don't even submit small changes in prose - never ever. Really. It saves a lot of time to have patches, as it's often easier to read diffs than intermingled description and code lines, which everybody does differently.
- Create unified diffs (diff -Nurb <old> <new>), they are easier to read. See below for further instructions on how to do that.
- Always diff from the parent or top-level MadWifi directory, so the whole path to modified files is included in the resulting diff files.
- Make one patch for each functional change (bugfix or new features). It's fine if one patch contains modifications to several files, as long as all these modifications belong to the same functional change.
- Submit your patches as plain-text files. Don't compress or encode them.
- Describe your patch. Adjust your verbosity to the complexity of your changes.
- Sign off your patch. DevDocs/SigningPatches explains what this is good for and how it's done.
Creating a patch: Step-by-step Guide
Think about what you want to change or fix. Only make one functional change at a time - this makes it much easier to review and discuss your changes later.
Start from a recent version of the code, and make sure you have a clean (not yet modified) snapshot. Getting the code as tarball is ok. But we suggest to get your snapshot via Subversion, as this makes it a lot easier to keep up with current development:
svn checkout http://madwifi-project.org/svn/madwifi/trunk madwifi
Create a working copy for each functional changes you're about to work on, by copying the whole directory:
cp -r madwifi madwifi.work
Work inside the working copy and don't touch the original snapshot, else it will be much harder to generate a proper diff. If you're going to work on several distinct changes at the same time, it's best to give meaningful names to each working copy (e.g. madwifi.fix-handover or madwifi.makefile-improvements).
Once your work is done and has been properly tested, change to the parent directory (the one that contains the clean snapshot and the working copy) and type:
diff -Nurb madwifi madwifi.work > patch-name.diff
This will create a diff file patch-name.diff with all the changes you've made.
If you're working with Subversion things are even easier, change to the toplevel directory of your working copy and type:
svn diff > ../patch-name.diff
Double-check that your diff contains all your changes (and nothing more).
Recovering existing patch(es) that are not in the preferred format
Do not despair or waste time if you have an existing patch that you would like to submit but which either doesn't follow the preferred conventions or is reversed by accident.
See the diffconvert project for tools that can be used to convert between the "context" and "unified" diff formats and tools that can reverse patches.
Submitting the patch(es)
Once your patch is ready for prime-time attach it to a ticket. These instructions explain the details.
In case you feel the need to discuss your patch, we suggest you start a new thread for that on the madwifi-devel mailing list and refer to the ticket that has the patch attached. Don't forget to explain what your patch is intended to do.
That's basically all. Not that complicated, right? You'll get used to this procedure very quickly. In case you're stuck at any point let us know, we're happy if we can help.