This is an old revision of the document!
You need to install the git command line tool, part of git-core (on Debian/Ubuntu) or git (Fedora/CentOS) package:
apt-get install git-core
Create the folder where you want to clone the repository, for example:
mkdir ~/kamailio cd ~/kamailio
If you have developer write access to GIT repository, clone the repository with:
git clone https://github.com/kamailio/kamailio.git kamailio-dev
or if you prefer via ssh:
git clone ssh+git://email@example.com/kamailio/kamailio.git kamailio-dev
You may be asked for your Github username and password.
The clone is tracking automatically the remote master branch (the development version).
If you don't have developer write access, you can clone read-only the repository with:
git clone --depth 1 git://git.sip-router.org/sip-router kamailio-dev
When cloning in read only mode, you can commit your changes to the local clone, but you cannot push the patches to the remote repository. Export the patches and attach them to an email to mailing list <sr-dev [at] lists.sip-router.org> or to an issue on bug tracker. A developer can pick them and commit in your behalf.
You can export the local commit with git format-patch, for example, exporting last commit:
git format-patch -1
The name of the patch file is printed in the terminal and the file is saved in current directory.
Not an absolute MUST, but it SHOULD be used almost always. It helps to track changes and follow the development easier (better commit mail messages and ChangeLogs are easier to generate).
Note: there is no list of owners and the code parts, the guidelines here are not to prevent contributions to any parts of code, but to keep the coherence of the code and sanity of development. As generic rule, if you are not the initial author of a component, then someone else is the maintainer. If you don't know who is that developer, just ask on mailing list sr-dev [at] lists.sip-router.org.
Whenever possible, commit first into master branch and then backport the patch - a recommended way is to cherry-pick the patch by commit id from master branch in your target branch.
By committing first into master branch, we ensure that the development version is always the most up-to-date. Also, people can review and test the commit from master branch before it is backported to a stable branch.
If it is a major change, then it is recommended to commit first into a personal or tmp branch. Then send an announcement to sr-dev mailing list, describing shortly the changes and where they are located. In this way, first, we avoid development conflicts between main (other) author(s) of the code and the other developers. Second, other developers can review or test, giving feedback or suggesting improvements or alternatives.
In some cases, the main author of the code may provide a different implementation, for the same purpose, that will fit better in existing architecture or future plans for that component. Very often, the contributions will be just merged in the main devel branch.
Each developer has access to a personal branch on GIT remote repository hosted on sip-router.org. The name of the branch starts with the GIT username of developer, followed by a forward slash and then the effective branch name. For example:
Only the respective developer can do commit in such branch.
If many developers need to work on a branch, it can be created in the tmp/ space:
Please create the commit messages following the GIT convention:
Think of the first line as of an email “Subject” line. In fact it will be used as “Subject” in the generated commit emails and it will also be used when generating the Changelog (e.g. git log –pretty=oneline).
Please start always with the prefix of the subsystem that is modified by the commit, for example:
If the module_name is duplicated, one in modules_k and one in modules_s, add (k) or (s), depending where the changes was done, for example:
Examples of commit messages:
usrloc(s): fixed name conflict - destroy_avps() renamed to reg_destroy_avps() to avoid conflicts with the usr_avp.h version.
core: loadpath can now use a list of directories - loadpath can use a list of directories separated by ':', e.g.: loadpath "modules:modules_s:modules_k". First match wins (e.g. for loadmodule "textops" if modules/textops.so or modules/textops/textops.so exists, it will be loaded and the search will stop).
The suggestions here target to make easier to track the changes and do the backporting to stable branches whenever is the case:
When you finish doing the changes, you can see affected files with:
If you are in the root of source tree, you can commit all changes with:
git commit .
In case you added new files, first you have to add them with:
git add path/to/file
To split the commits, you can give the list of files as argument to git commit command:
git commit path/to/file1 /path/to/file2
You can commit the changes in a directory with:
git commit path/to/directory/
For example, commit the changes for module auth:
git commit modules/auth/
Example commit message to auth module:
auth: improved documentation for www_challenge()
Example commit message:
lib/srutils: more detailed log message for uuid generation
Commits that include fixes to issues affecting stable branches must be backported using:
git cherry-pick -x _COMMIT_HASH_
git cherry-pick -x a8bc3d
Parameter -x is important to be able to keep track easier of backported commits.
The git cherry-pick command must be executed inside the branch where the commit has to be backported, after doing a git pull origin.
Note: the commit must be done first time in master, then backported to the latest stable branch, using cherry-pick -x with commit id from master. The backported commit gets a new id in the latest stable branch, that commit id must be used when cherry-picking to the previous stable branch. When willing to backport to older versions, keep using the commit id from the next stable branch.
This section collects some useful GIT commands.
git reset --hard HEAD~1
git reset HEAD~1
git reset --soft HEAD~1
git checkout -b local-branch-name origin/remote-branch-name
git checkout -- file-name
git commit --amend
git add --edit
git revert HEAD^
git push origin :<branchName>