Participating in the development
X-Smiles is an non-profit open-source project with a license similar to the Apache licence. Everybody is encouraged to participate in the development.
This document describes the details on how to create and submit patches, and which kind of coding style should you use when creating code for the project.
All developers should follow the coding style defined in this document
Use 4 spaces instead of tabs
Creating and applying patches
First, make sure you are making changes in the most recent version of the sources - for this, it is best to use SVN to check out the source (usually on the SVN trunk; sometimes the most active release branch - ask if unsure), make your modifications (but do not check them in), and then run (example for Unix, other operating systems similar):
$ cd /source/xsmiles
$ cvs update src
$ cvs diff src
$ cvs -f diff -u -N src > /tmp/my-patch.diff
If you are adding or modifying binary files, it is best to attach the new or modified binary files separately and exclude them from the textual patch.
Common patch mistakes include:
-u. Default-format diffs show no context and will be hard to read and apply, especially if they were made against somewhat out-of-date sources.
-c is also OK but
-u is most common.
Forgetting about new (added) files. Run
cvs add (but do not commit!) to make sure SVN thinks of them as added as part of the patch, and remember
-N which includes them in the patch. Also run
cvs remove (but do not commit) when a patch should delete some files.
Using other switches such as
-t which can make the patch difficult to apply.
Starting from the wrong directory. Always make patches from the root of the source tree to avoid confusion.
Manually editing patches. You may be tempted to concatenate patches, or manually edit them to exclude things you do not really want to submit. Do not do this. The patch may be corrupted as a result. Fix your sources to reflect what you want the result to be, and run a fresh diff. Include all affected files in the diff command, even if they are in different modules.
Including extraneous changes. Look over your patch to make sure every change relates to the fix you are making, and is necessary. Remember other people will read your patch before applying it! Do not make gratuitous whitespace changes. Do not reformat existing code you are not modifying.
Using the plain diff command. Use
cvs diff to ensure that exact information about repository path and original version of the patched files is retained.
Using old sources. Patches made against obsolete sources may be hard to use. Make sure you are using recent versions of all source file (
cvs update first). If you must submit several patches against the same files, be sure to indicate if they must be applied in some particular order.
A properly made patch is easy to apply by someone with commit access who has reviewed it. Use of the Unix
patch tool is recommended; Windows users should be able to get it from the Cygwin tools distribution.
$ cd /sources/netbeans/nb_all
$ patch -p0 --dry-run < /tmp/suggested-patch.diff
$ patch -p0 < /tmp/suggested-patch.diff
$ cvs diff beans/
If the "dry run" fails, you may need to use additional options to
patch, or at worst just apply the patch manually. Do not forget to sanity-check file additions and removals! You probably need to use
cvs add and
cvs remove to complete these.
Making patches available
The preferred way to make a patch available is to send it to the firstname.lastname@example.org mailing list. The instructions on how to subscribe can be found here.
Another way is to include the patch as an attachment in a bug report in the bug area.
The SVN access is desribed in the CVS page
Copyright (c) 2000-2008 X-Smiles.org et.al.