Submitting patches

The bottom line: Attach an unified diff against svn trunk.

User feedback and, especially, patches are very important for OpenNX. They often help us improve OpenNX' quality and fix bugs, so we are of course happy if you contribute them (how could we dislike your help, after all?). But 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 to mailing list and we'll do our best to help you.

Rules

Use the latest version: Please always make your patches against the latest version of OpenNX. In most of the cases, you should make a patch against SVN trunk. If you cannot access SVN (for example when you are behind a firewall), make the patch against a fresh SVN snapshot (downloadable from here).

Adhere to formatting of existing code: Indentation of 4 spaces, no tabs, braces for conditionals and related blocks on the same line, braces for methods and functions on the next line, space between conditional keyword and the following expression.

Standard patch format: Do NOT attach ZIP archives, whole files or even worse, only code snippets. Patch is something that we could apply with one command, not arbitrary text that we'd spend hours trying to understand.

The advantage of using diff is that it produces one file with differences in all files you modified and what's more, diff files are small, easy to read and understand and can be applied even if the affected files have been changed since the moment when the patch was submitted. The only exception to this rule is for the translations: unfortunately, .po files change a lot each time they are regenerated because all line numbers recorded in them change, and this risks making any patches to them unappliable very quickly. So for these files, and only for them, please submit the whole files and not patches to the existing ones. You can use diff program which is a standard part of most Unix systems and is available as part of cygwin package or elsewhere for Windows or, alternatively, you can just use svn diff command which works almost in the same manner as diff if you are already using SVN. The best way to make a patch is to use this command:

svn diff > mypatch.patch

If you use a standalone diff use -u option, i.e.:

diff -uNr OpenNX-orig OpenNX-mine

If your patch adds or removes files you should run svn add or svn remove before using svn diff if you're using svn for making the patch. And if you use a standalone diff program locally, you need to use -N option for the new files to be included in the patch.

Don't include auto-generated files (config.h, Makefiles, etc.) in the patch. Everything that is deleted by make maintainer-clean should not be included in a patch. The simplest way is to run make maintainer-clean before creating a patch. After creating the patch, you can re-create those files by running make -f Makefile.am

Make atomic patches: Do not split single code change into multiple patches. A patch should be self-contained -- one patch for one thing. A patch that adds bitmaps to the GUI and fixes a bug in MySession is a bad patch. It should be splitted into two patches. On the other hand, two patches, one of them being "implementation of new member-functions", the other "changes in class description to accomodate new members" are two bad patches. They are related to one, logically indivisible, thing, so they should be part of one patch. Also note that it is not possible to upload multiple files at once -- this is why you should use diff which produces one small file. Another example: if you adapted the build system to work on new, previously unsupported platform, we would gladly accept your patch. Just please send us single patch, not 10 patches, one for each modified file.

Use standard extension .diff or .patch for the patch file.

Use SF's patch tracker: Please do not send the patches to the mailing list, nor to any developer's personal email address. Instead, use the tracker. Then you will be automatically notified when the patch is accepted or if there is a problem with applying the patch. Of course you need a working notification mail address in your SF user profile.

Describe your changes: Please fill in the form and describe the patch as precisely as possible in the Description field. Remember that it is often not easy to understand the purpose of your patch just from its source code. Alternatively, you may post a message explaining what your patch does to mailing list. 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 :)

Let us know your name: Concerning the latter, 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 about it if we don't know you already from your posts to the mailing list.