-
Notifications
You must be signed in to change notification settings - Fork 77
How to Contribute
- Getting the source code
- How to work with Wok submodules
- Submitting changes
- git-sendemail configuration
- Commit changes locally
- Create the patch files
- Send patch to the mailing list
- Getting your contribution accepted
- Code style
- Cover letter
- Commit message
- Patchset
- Copyright
- Imports
- Unit tests
- Test your patch
- Build process
- Comments
- Documentation
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.
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:
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.
$ 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>
$ 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.
$ 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
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).
Unless specified in a different way below, this project follows the PEP8 guideline.
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.
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.
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.
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.
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.
All contributions must have unit test support, if applicable. At the very least the contribution must not break any additional unit tests.
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.
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.
Keep your code clean. The code must be easy to follow and to maintain. Only use comments when necessary.
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.