Last Modified: 2019-06-25

Contribute code

From SipLCS

The SipLCS git repository has a branch called mob which may be changed by anyone using the user mob without requiring any authentication. This means that the branch is effectively world-writable and you can use it to commit changes without asking anyone for permission.

1. Getting the Code

Clone the SipLCS git repository using mob as user name. The mob user doesn't require any password.

git clone -n git+ssh://mob@repo.or.cz/srv/git/siplcs.git

Every git command after the initial cloning needs to be executed in the siplcs directory.

cd siplcs

Create a new local branch mob tracking the remote mob branch.

git checkout -b mob --track origin/mob

2. Changing the files

Now you can make changes to the files locally.

Test your patch:

1. Run make and SipLCS itself and make sure you did not introduce other bugs!
2. Optionally, run git diff to see what you modified, run git checkout <filename> to revert your changes
3. If everything works fine and when you're satisfied, proceed to the next step.

3. Preparing to commit changes to the server

Step 1: Identify

To make sure that your commits have your name and email address, create the file ~/.gitconfig

[user]
name = "Your Name"
email = "your@email.address.xz"

Step 2: Commit your changes locally

On the command line

First review what files you have changed.

git status

Add the files you want to commit

git add <filename> #To add one file
git add -u         #To add all the files changed locally (visible with 'git status')

Then create the commit itself. This launches a text editor to allow you to enter a commit message. Please try to describe what your patch changes exactly without being overly verbose. A useful commit message increases chances that you patch will be merged to the master branch.

git commit

With the help of a GUI

Git also allows you to commit with the help of a GUI. Among other things this has the advantage that you can also select which individual hunks you'd like to commit.

git-gui

Step 3: Merge upstream changes

If you got the code of the mob branch and before you upload your patch, somebody else committed a patch to the same branch, you should try to get and merge the updates first. Otherwise the changes already in the repository will be committed twice.

git pull              # retrieve updates from server
git merge origin/mob  # merge changes into local mob-branch

If your local changes conflict with the newest source code, it will tell you and refuse to apply the remote patch.

4. Send changes for review and commit

!!! DO NOT PUSH UNREVIEWED CHANGES TO "mob" YOURSELF !!!

If you do the maintainers will remove your changes without notification.

Please send your commit for review with the following commands:

git format-patch -n -o outgoing/ HEAD^                      # prepare commit in email format
git send-email --to <insert email address here> outgoing/*  # repeat option for multiple addresses

After the review process has been completed, the maintainers will commit your changes and they will become visible to the world at http://repo.or.cz/w/siplcs.git?a=shortlog;h=mob

6. Other useful GIT stuff

You can see what you modified by doing:

git status

To see the differences:

git diff <somefile> # differences within a file 
git diff # all differences in the current map of the branch

And to restore the file to its original version:

git checkout <filename> # restore a file
git checkout -f # restore everything

[Summary: forget to change two occurences of cg to git]

7. Documentation

• A useful 'Kernel Hackers' Guide to git' can be found at http://linux.yyz.us/git-howto.html

8. Valgrind

Valgrind is powerful dynamic analysis tool that can f.ex. help to find memory leaks in the code. As the code uses glib we need to configure its memory allocator to behave nicely while running under valgrind:

G_DEBUG="gc-friendly" G_SLICE="always-malloc" valgrind --leak-check=yes pidgin --debug
 

9. Internationalization

9.1. Translatable texts were added/removed/modified in the code

If you modify translatable texts in the code, i.e. those places that use either _() or N_(), then the translation files need to be updated too. Otherwise translation services like Transifex won't be able to show the correct translation completeness status. The commands to update the PO files are:

(cd po; intltool-update -r)
git add po/*.po

You should either include the PO files update in the same git commit as the code changes or as a separate git commit in a group of related commits.

9.2. Committing a translation file

If you want to commit a (contributed) translation file, please follow these steps:

git pull
cp path/to/copy/of/new/translation/file/XYZ.po po
(cd po; intltool-update XYZ)
git add po/XYZ.po
git commit -e --author "Full Name <email@address.domain>"

This will make sure that the committed translation file corresponds to the latest source code and the contribution of the translations' author is honored in the commit.

9.3. Contributing translations

Updates to the translations in the PO files can be contributed directly via git commits. If you don't feel confident enough to use git then you can contribute your translation updates via the Transifex web page.