User Tools

Site Tools


devel:git-commit-guidelines

This is an old revision of the document!


GIT Commit Guidelines to Kamailio Repository

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

Where to commit

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.

Changes to your part of code

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.

Changes to other parts of code

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.

TMP and Personal branches

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:

daniel/tm-updates

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:

tmp/tm-changes

Commit message

Please create the commit messages following the GIT convention:

  • start with one short line, preferably less then 50 chars summarizing the changes (this is referred later as “first line of the commit message”)
  • then one empty line
  • then a more detailed description

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:

  • core: typo fixes
  • tcp: stun fixes
  • mem: faster malloc
  • module_name: support for foo
  • lib_name: critical bug fix

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:

  • auth_db(k): fixed typo in comment
  • auth_db(s): fixed typo in comment

Examples of commit messages:

  • change to usrloc module from modules_k
usrloc(s): fixed name conflict

- destroy_avps() renamed to reg_destroy_avps() to avoid conflicts
  with the usr_avp.h version.
  • change to core
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).

See:

Generic Guidelines

The suggestions here target to make easier to track the changes and do the backporting to stable branches whenever is the case:

  • commit big changes across many parts of the code in smaller chunks that affect only one part. Examples of major code parts: parser, transport layers, config interpreter, memory manager, libraries, modules, …
  • do the commits per one module when changing in a module and other modules are affected and were updates as well
  • when updating the documentation and it is intended to do a backport, split the commit in one for xml files and one for the README file. Usually the commit to xml files can be backported without conflict (with git cherry-pick …). README files are many times generated with different character sets, a matter of the system where they are generated, resulting in backporting conflicts. Thus is better to backport only the commit for xml files and generate the README for that branch, then push it to remote GIT repository
  • if it is a change that has to be repeated in many places, then the commit can be done at once to all changes. For example, renaming a token that is present in all docbook files, removing or adding a new field in a structure such as module exports.

Splitting commits

When you finish doing the changes, you can see affected files with:

git status

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/

Core Commits

  • prefix the first line of the commit message with “core:”, or with the subsystem prefix (e.g. “tcp:”, “dns:”, “mem:”, “script:”, a.s.o).

Module Commits

  • prefix the first line of the commit message with “module name:”
  • if there are modules with same name in different directories, use a distinctive marker to give a hint about which one was updated. Recommended markers are:
    • (k) - for modules located in modules_k
    • (s) - for modules located in modules_s

Library Commits

  • prefix the first line of the commit message with “library name:”
devel/git-commit-guidelines.1321873012.txt.gz · Last modified: 2011/11/21 11:56 by miconda