Participating in the development

General

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.

Coding style

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
$ ls

shows...

$ cvs update src ...or wherever your changes are; may be >1 module


make sure you are working against current sources

$ cvs diff src

sanity-check the change

$ cvs -f diff -u -N src > /tmp/my-patch.diff

sanity-check the patch

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:

Forgetting -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.

save patch to disk, say /tmp/suggested-patch.diff

$ cd /sources/netbeans/nb_all
$ patch -p0 --dry-run < /tmp/suggested-patch.diff

make sure no errors are reported - this just tests the patch format

$ patch -p0 < /tmp/suggested-patch.diff
$ cvs diff beans/ or whatever part of sources are affected


sanity-check diff, compare to patch (should be same or similar)


test, do a build, commit as usual

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 developers@xsmiles.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.

SVN Access

The SVN access is desribed in the CVS page.