Skip to content

Contributing

Jump to bottom Edit New page
Tobias Blomberg edited this page Jun 29, 2014 · 20 revisions

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.

Contributing documentation

To be written…​ :-)

Qtel language translation

To be written…​

SvxLink Server language translation

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!

Some guidelines for contributing code to SvxLink. If these are not followed it will take me longer to accept the patch and if it’s really bad it will be rejected all together.

  • Before putting in a lot of time to code a feature, send an e-mail to the svxlink-devel mailing list to see if someone else is working on something similar and that what you are about to do is in compliance with the architecture in SvxLink.

  • Stick to the coding standards. Just look at existing code and do the same. Examples:

  • Never ever change the TAB size in your editor. It should always be eight characters.

  • Indentation should be two spaces.

  • No single line of code should exceed 80 characters unless it is impossible to break it up.

  • Variables are always in small caps. Words should be separated using underscore (e.g. my_variable)

  • Member variables may be prefixed with "m_" to distinguish them from other variables (e.g. m_my_member_variable).

  • Type and class definitions are written in upper camel case (e.g. MyClass)

  • Member and class functions are written in lower camel case (e.g. myFunction)

  • Macros and static constants are written in all upper case (e.g. MY_CONSTANT)

  • One patch should ideally contain one new feature. If it contains a mix of features it will be harder to review the patch and also harder to accept one feature if another feature is not OK.

  • Update the appropriate manual page if you have added a new feature.

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

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 URL (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.

Subversion examples

Here are some examples for developers for how to use Subversion in the SvxLink project.

Checking out trunk

Checking out trunk is probably the first thing you want to do. The checkout can be done on the trunk level but it’s often more practical to do it on the src level instead.

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

Creating a branch is simple. There is no separate branch command in Subversion. Instead, the copy command is used. It’s easiest if you are standing in an already checked out source tree, for example trunk. Then the full URL:s does not have to be written.

svn cp ^/trunk ^/branches/my_branch -m "Created new branch my_branch"

Choose a good branch name which describes the purpose for it.

Checking out a branch

Checking out a branch is just as simple as checking out trunk.

svn co https://svxlink.svn.sf.net/svnroot/svxlink/branches/my_branch/src my_branch-svxlink
Merging latest changes from trunk

Merging trunk into branches should be done by the branch maintainer regularly so that trunk and the branch don’t drift too far apart.

Merging has been made much simpler in Subversion since version 1.5 when merge tracking was introduced. Before that, one had to manually keep track of which revisions had been merged previously. Now it’s quite simple if you follow the guidelines below. Merging always have to be done in a clean source tree to not risk checking stuff in that has nothing to do with the merge. If your normal working copy is not clean, just check out a new clean copy.

Start by making sure that the source tree is up to date.

svn up

Then make sure it’s clean. Only the current revision should be printed.

svn st

Merge the latest changes from trunk.

svn merge ^/trunk/src

Now fix any conflicts that was encountered. Files that have status "C" have a conflict. The files that have conflicts can be found using the following command.

svn st | grep ^C

When a conflict has been fixed, Subversion must be told so.

svn resolved path/to/file.cpp

Now make sure everything looks good and that it compiles. Always check the diff so that nothing unintentional will be checked in.

svn diff

If you’re in a graphical environment, the diff can be piped to a graphical diff application, for example "kompare".

svn diff | kompare -

If everything looks good you are now ready to check the merge in. The checkin message should contain the word "Merge" so that the merge points can be easily found in the log later. Also include the branch name. A good template look like this:

svn ci -m "Merged latest changes from ^/trunk/src into the my_branch branch"
Add a custom footer
Clone this wiki locally