This is an old revision of the document!
Cafu is to a large degree a community project, and we need and very much appreciate your help. Your contributions and especially patches are very important for Cafu. Patches help us to add new features, improve code quality and fix bugs, so we are happy and grateful if you contribute them.
However, we have all sort of problems with applying non-standard patches. To make life easier for both you and us, please follow the few simple rules below when submitting patches.
Remember that if you have any questions about the steps here, you can always post them at the Cafu forum and we'll do our best to help you.
Please read the Coding Conventions and try to conform to them. In particular, please respect the indentation rules (4 spaces, no TABs) – patches are really difficult to read otherwise.
Bug fixes and elegant program solutions often involve complex code that can be difficult to understand without documentation, and an undocumented new feature is hardly useful to anyone but its author.
Therefore, please provide any required documentation such as source code comments (preferably in familiar and simple Doxygen format), high-level overviews, diagrams, etc. Without documentation, another developer would have to write it, and the patch cannot be applied until he has time to do it.
Always make your patches against the latest version of Cafu.
In most of the cases, you should make a patch against the head revision of the SVN trunk. You can learn how to checkout the source code from the Subversion repository here.
If you cannot access the Subversion repository (for example when you are behind a firewall), make the patch against the latest source code release from the Downloads page.
A patch is a single file that contains the differences in all files that you modified. Patch files are small, easy to read and understand and can be applied with a single command, even if the affected files have been changed since the moment when the patch was created.
Therefore, do not send us ZIP archives, whole files, code snippets or other arbitrary text that we'd spend hours trying to understand.
There are several ways to create patches:
svn diffat the command-line.
svn diffat the command-line:
svn diff > mypatch.patch
Similar to TortoiseSVN, if your patch adds or removes files, you should run
svn add or
svn remove before
diffprogram which is a standard part of most Unix systems and is available as part of the Cygwin package or elsewhere for Windows:
diff -uNr Cafu-src-orig Cafu-src-mine > mypatch.patch
-u option for unified diff output and
-N for the new files to be included in the patch.
Use standard extension
.patch for the patch file.
Don't include auto-generated files (log files, temporary scripts, etc.) in the patch.
The simplest way to handle this is to use TortoiseSVN, which allows you to select which files should and which files shouldn't be included in the patch. Alternatively, it is also easy to edit the patch to remove the unwanted chunks.
A patch should be self-contained – one patch for one thing.
Do not combine multiple new features in a single patch: A patch that adds bitmaps to menu items and fixes a bug in the network code is a bad patch. It should be splitted into two patches.
On the other hand, do not split a single code change into multiple patches: Two patches, one of them being “implementation of new member-functions”, the other “changes in class documentation to accommodate new members” are two bad patches. They are related to one, logically indivisible thing, so they should be in one common patch.
Please do not send the patches to the forum, mailing list, or to any developer's personal email address. Instead, use the issue tracker. Then you will be notified about the progress the patch makes, e.g. when the patch is accepted or if there is a problem with applying the patch.
Please fill in the ticket form as explained at SubmitTickets.
Remember that it is often not easy to understand the purpose of your patch just from its source code. If you provide detailed description of the patch, we will be able to apply it much faster – and we will love you for submitting such nice patches!
We'd also like to give you credit for your patch (unless it's something really trivial as we avoid mentioning very small changes in our changelog) but we need to know your real name for this. Please tell us if we don't know you already e.g. from the forum.
From a strictly legal point of view, when you submit a patch or another contribution, you are the copyright holder of your contribution, and CFS is the copyright holder of Cafu. If we now integrated your contribution into Cafu, the result would be a mixed edition that is partly copyrighted by CFS, and partly copyrighted by you. Over time, the mix would grow more and more intermingled, to the extent to which many contributions from many different authors were merged in. The end result would quickly become an unmanageable and chaotic mess.
As a consequence, not being the exclusive copyright owner any more, we would no longer be able to make crucial decisions on behalf Cafu as a whole:
These actions would instead require the consent of all copyright holders of the new, “mixed” Cafu edition, and all future editions that are ever to be released — a practical impossibility.
Here is the single most pressing question that we assume occurs to most people now:
|Wait a moment! You plan to earn money from an edition of Cafu that my (substantial) contribution has been integrated in??|
When a patch is submitted at the issue tracker, it is integrated into the official Cafu source code, from where it is available under the GPL and the commercial licenses. Please consider why we still think that this is a win for you as well:
In summary, the assignment of copyright is not only legally necessary; we also believe that it is fair, preserves your rights, and generally helps free software.
If you disagree, please let us know what bothers you. We'll do our best to answer your questions and fix whatever is wrong. But please understand that if you disagree, you cannot use the issue tracker for submitting your patch, and that we thus cannot accept and integrate your contribution into the Cafu Engine.