How to Contribute

Getting the source code

Ginger Project uses Git to source versioning/controlling/management, and it's remote and official repository is hosted at GitHub. To clone the source code into your local repository, you only need to execute this command:

$ git clone https://github.com/kimchi-project/ginger.git

To get the latest updates you only need to execute:

$ git pull

Need documentation about how to use Git? See this documentation.

Submitting changes

All patches are sent through our development mailing list hosted at Yahoo! Groups. More information can be found at:

Ginger Project Discussions and Patches

Patches should be sent using git-send-email (use your Linux distro package manager to get it). A good point of start is described in the steps bellow:

1. Add into .git/config file the following content (modify the content between <greater-than and less-than signs> with your personal information):

[alias]
    makepatch = format-patch --subject-prefix=\"PATCH\" --cover-letter
    askreview = send-email --no-signed-off-cc --smtp-server <your SMTP server> --from \"<your email address>\" --thread –annotate
[sendemail]
    to = Ginger Devel <ginger-dev@yahoogroups.com>
    cc = Zheng Sheng Zhou <zhshzou@linux.vnet.ibm.com>
    suppresscc = all

This content is setting up two new Git aliases into your local repository configuration: makepatch and askreview. The first alias should be used to create patch files to be sent to community review (details how to use in subsection 3). The second alias should be used to send the patch to development mailing list (details how to use in subsection 4). In addition, the section [sendemail] sets up the addresses and arguments to be used by the askreview alias.

2. Commit changes to your local repository/branch:

$ git commit -s <files_modified>

While writing the commit message, add the issue number in the first line if you are fixing some issue. An example is:

Issue #<number>: <issue_label>

<message describing the bug fix>

3. Create the patch files:

$ git makepatch origin/master

The origin/master branch can be changed to any other branch you want to use as base to create your patch.

4. Send patch to list

$ git askreview *.patch

The *.patch can be changed to a specific patch file, or a list of patches, like:

$ git askreview 0001-add-token-bucket-support.patch 0002-usage-of-token-bucket-in-network.patch

Reviewing Patches

Since patches are sent to ginger-dev mail list on Yahoo groups, you can just subscribe to the mail list to receive all the patches. You can use Thunderbird plugin ImportExportTools to export the patches to an mbox file. Then use git am patch.mbox to apply the patches to your local repository and test them.

Unfortunately, Yahoo Groups delivers the mails in both plain text and HTML version, even if we configure it only use plain text. So the e-mail body is actually a multipart message, containing both plain text and HTML version, and this interferes the git am command. We have a small script "mboxclean.py" to solve this problem. Just download the script, chmod +x mboxclean.py, and run ./mboxclean.py patch.mbox, then it will remove all the HTML parts of the message, and the resulting file patch.mbox.clean can be used in git am command successfully.