Contributing

Contributing to the SvxLink project

There are a lot of ways in which you can contribute to the SvxLink project. Even if you are not a programmer, you can still contribute other things.

Qtel language translation

To be written…​

SvxLink Server language translation

To be written…​

Contributing documentation

To be written…​

Contributing code

All new features should be developed using the latest code from Subversion. Check the source tree out like this:

svn co https://svxlink.svn.sf.net/svnroot/svxlink/trunk/src svxlink

Have a look at the InstallationInstructions page for information on how to compile and install SvxLink from source code. Start developing!

Creating a patch

When you are satisfied with your work, send a patch to the mailing list (svxlink-devel@lists.sf.net). The patch should be created from the top source directory, never from a subdirectory. The top source directory is the one corresponding to ^/trunk/src in Subversion. That’s the one we checked out above. The reason for always creating patches from the source root is that the patches are easier to apply then. Otherwise one have to first figure out from which directory level it was created to be able to apply it.

Creating a patch is very simple. If everything you have changed in the source tree should go into the patch, use the command below.

svn diff | gzip > /tmp/my_new_feature.patch

If you don’t want to include all changes in the patch, just point out the directories and/or files that you want to include. This should still be done from the top source directory. Don’t cd into the subdirectory you want to create a patch for. The command below will for example create a patch of all changes in the async directory and the changes in the file svxlink/svxlink/Logic.cpp.

svn diff async svxlink/svxlink/Logic.cpp | gzip > /tmp/my_new_feature.patch.gz

Note that there is a 100kB limit set up on the mailing list so if the patch is bigger than that, you’ll have to break it into multiple parts. This can be done using the split command.

split -b 90k my_new_feature.patch.gz my_new_feature.patch.gz.

This will produce 90k chunk files called my_new_feature.patch.gz.aa, my_new_feature.patch.gz.ab etc. Send each part in separate e-mails.

Subversion write access

If you contribute a lot of code, handling patches start to become a burden for both the contributor and for the one who are going to apply and check in the patches. If this is the case, you may be given write access to Subversion. However, this is not something that is lightly handed out. There should be a concrete need and you need to have contributed a number of bigger patches first.

The following guidelines should be followed or your write access may be revoked.

• For now, I (Tobias) want to be the only one checking code into trunk. That includes merging from branches unless I say otherwise.

• Try to keep branches as clean as possible. One branch should contain one new feature, if possible. Try to avoid lumping a lot of new features into one "personal" branch. The risk here is that the branch will grow larger while new features are added but not finished. Creating separate branches for each feature will encourage finishing implementing a feature so that it can be merged to trunk and then merged into other branches that need it.

• When creating a new branch, always do that from trunk and not from a subdirectory: svn cp ^/trunk ^/branches/my_branch, where ^ is an alias for the repository root (introduced in Subversion 1.5). This will reduce confusion.

• You are responsible for keeping your branches in sync with trunk. This is to make later merging easier and of course so that you get the latest features into the branches. It’s pretty easy to do as well unless lots of changes conflict. Then it can be a bit of a pain. This should not be a big problem unless we start to have a lot of overlapping features being developed at the same time. Just do a "svn merge ^/trunk" now and then. You may need to modify that path, depending on how you checked out the svxlink source tree (e.g. svn merge ^/trunk/src).

• All checkins should have a meaningful comment. This is very important. The checkin comment will be shown on the "Trac Timeline" so it serves as information to other users of what is going on. It is also very important to have a good comment if one want to go back to check when something specific was changed. Maybe a bug was introduced at some point. It will be easier to find if a good comment is used.

• Try to check stuff in together that belong together in one go. Don’t check it in file by file.

• Don’t check multiple changes in together that don’t directly belong together. One may later want to remove something that was checked in earlier. That will be much harder if multiple unrelated changes are lumped in the same checkin.