Skip to content

How to Contribute

Jump to bottom Edit New page
Aline Manera edited this page May 22, 2019 · 16 revisions

Getting the source code

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

$ git clone https://github.com/kimchi-project/wok.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 oVirt Project. More information can be found at:

http://lists.ovirt.org/mailman/listinfo/kimchi-devel

Make sure to subscribe to mailing list prior to send patches. Otherwise, your patches will not be delivered.

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

git-sendemail configuration

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] [Wok\" --cover-letter
    askreview = send-email --no-signed-off-cc --smtp-server <your SMTP server> --from \"<your email address>\" --thread --annotate 
[sendemail]
    to = Kimchi Devel <[email protected]>
    cc = Aline Manera <[email protected]>
    suppresscc = all
    assume8bitEncoding = UTF-8

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.

Commit changes locally

$ git commit -s <files_modified>

While writing the commit message, add the issue number in the first line if you are fixing some issue as described below:

Issue #<number>: <issue_label>

<message describing the bug fix>

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.

Send patch to the mailing list

$ git askreview *.patch

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

$ git askreview 0001-Configure-to-ignore-changes-in-Wok-submodules.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).

Code style

Unless specified in a different way below, this project follows the PEP8 guideline.

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.
  • Known limitation.
  • 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.

The cover letter 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.

Commit message

Always add 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.

Patchset

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

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.

Unit tests

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

Test your patch

All contributions must pass the "make check" and "make check-local" verifications. It will check for any unused i18n strings, unused variables and pep8 warnings/errors. And also confirm your changes do not add cause regression.

Build process

Make sure to update the build process when needed. Test the RPM/DEB package generated with your changes to make sure everything keeps working as expected.

Comments

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

Documentation

Make sure to have the project documentation updated according to your changes. Basically, when an API is added/removed/changed, you will need to update the docs/API.md accordingly.

Mockmodel

Mockmodel is a fake model to simulate the real environment without making any changes in the system. When running wokd with "--test", the mockmodel is in action. It is really important for tests. So make sure to have it update according to your changes.

UI Development

Make sure to update the CSS files when modifying the SCSS files by running:

$ sudo make -C ui/css css

The modification added to the application CSS file must be added as part of your patch.

How to contribute translations

WoK uses GNU Gettext for internationalization. For those not familiar with gettext, the following quick tips should help you to easily perform some basic tasks related to the WoK i18n:

If you add new translatable strings to any existing *.html.tmpl file, Then you need to update the translation catalog and rebuild the object files under the top workspace directory, please make sure "./autogen.sh" have been completed successfully before run "make":

make -C po update-po
make -C po all

After which, information about the messages that have/haven't been translated and also some fuzzy translations are provided. Fuzzy translations are translated by Gettext and possibly need some improvement which looks like this:

#, fuzzy
msgid "Untranslated sentences"
msgstr "Sentences translated by Gettext"

Remove the annotation with word "fuzzy" which starts with a pound sign and check whether the msgstr message is appropriate. If not, please have it changed to the correct one.

If you add a new *.html.tmpl file, Then you must add that file to the list of files that contain translatable strings:

echo "ui/pages/new.html.tmpl" >> po/POTFILES.in

If you want to add support for a new language, Then you must register the new language code and rebuild.

echo "xx_XX" >> po/LINGUAS
make -C po all

If you want to check the status of translations, Then run the following command:

rm po/*.gmo
make -C po update-gmo

Since the patch i18n patch could include non-ASCII characters, you will get the following prompt:

Which 8bit encoding should I declare [UTF-8]?

when you send the patch by git-send-email. You could just press ENTER to accept the UTF-8 as the encoding. Or you could specify it you git config like this:

[sendemail]
assume8bitEncoding = UTF-8
Add a custom footer
Add a custom sidebar
Clone this wiki locally