How to Contribute

Getting the source code

Ginger-s390x 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/gingers390x.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 ginger-dev-list@googlegroups.com.

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] [Ginger-s390x\" --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-list@googlegroups.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

Getting your contribution accepted

Here's a few pointers that guides the reviewing process of all projects under Kimchi Project (Ginger and all its plug-ins, Kimchi and WoK):

• Cover letter: unless you're sending a trivial patch (typo fix, etc), we'll require a cover letter explaining:

  • The goal of the contribution.
  • How to test it. Make it easier for the community to test and assert it works.
  • Changelog of the patches (what changed from the last version). This helps the reviewer identifying if a comment he/she made was attended to or not.

• Make your patches small. Unless you've changed thousands of lines in the same file, break the contribution in smaller commits to make the review process easier.

• Descriptive commit message. Again, for trivial patches it is ok to just write "Fixed a typo" and get it over with. Otherwise, you must explain the changes you've made with this specific commit.

• When fixing an issue from Github, do not just say "This fixes Github bug #X". You must provide a brief explanation of the bug and how you've fixed it. The developer must be able to understand the bug and the fix by just reading the git log and, if he/she requires more information about it (the bug discussion for example), he/she can access the github issue directly.

• Keep your code clean. The code must be easy to follow and to maintain. Only use comments when necessary.

• Copyright: pay attention to the copyright date. New files should contain only the current year, while older files will contain the year it was created and the year it was last modified.

• Imports: we keep the python imports in alphabetical order to make it easier to look for a specific import. Relative imports are kept after the absolute imports in alphabetical order as well.

• make check-local: all contributions must pass the "make check-local" verification. It will check for any unused strings in i18n, unused variables and pep8 warnings/errors.

• rpm/.deb builds: if the contribution breaks the RPM/.deb build, it will not be accepted. It is not a common scenario but it happens when adding new models or modules.

• unit tests: all contributions must have unit test support, if applicable. At the very least the contribution must not break any additional unit tests.

• Use the cover letter wisely. The cover letter is the place where you explain the goal of your patches, how to test it, known limitations and so on. It also makes it easier to comment/approve the whole patch set by replying in the cover letter instead of replying +1 in each patch individually.