|Version 10 (modified by sm0svx, 7 months ago)|
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.
To be written... :-)
Qtel language translation
Creating a translation to another language for Qtel is rather simple. First you should install the software used for doing the translation. It is called Qt Linguist. In Fedora 14, for example, the package containing this utility is called qt3-devel. Then you need to get hold of a file containing the strings that should be translated. The easiest way to do this is to download the latest template file directly from this link: http://svn.code.sf.net/p/svxlink/svn/trunk/src/qtel/translations/qtel_tmpl.ts. Rename the downloaded template file, replacing "tmpl" with your ISO 639 language code. The language code consists of two or three letters (e.g. sv=Swedish, en=English). If you are not sure what your language code is, have a look on this page for example: http://www.loc.gov/standards/iso639-2/php/code_list.php. Use the two letter variant if available.
Now start Qt Linguist from the menu Programming/Qt3 Linguist and open the template file or launch it directly on the command line with:
Start translating! Help on using Qt Linguist is available inside that application so I won't repeat any of it here.
When you're done, compress the file (e.g. gzip qtel_xx.ts) and send it to the email@example.com mailing list.
Language translations already available are: German (de), Spanish (es), Hungarian (hu), Russian (ru), Swedish (sv), Turkish (tr) and Ukrainian (uk).
SvxLink Server language translation
To be written...
All new features should be developed using the latest code from Subversion. Check the source tree out like this:
svn co svn://svn.code.sf.net/p/svxlink/svn/trunk/src svxlink
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 wide.
- 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 (firstname.lastname@example.org). 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.
- Don't check stuff into other branches than your own unless you have permission from the branch owner/creator.
- 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.
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 --username=user svn+ssh://email@example.com/p/svxlink/svn/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 --username=user svn+ssh://firstname.lastname@example.org/p/svxlink/svn/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.
Then make sure it's clean. Only the current revision should be printed.
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.
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"