Notice: MediaWiki has been updated. Report any rough edges to marcan@marcan.st

Contributing Code

From OpenKinect
Jump to: navigation, search

OpenKinect uses git on github for source control. Git is a distributed version control system (DVCS). You may want to study http://progit.org/book/ if you are not familiar with Git.

Repositories

OpenKinect has several official repositories and potentially many unofficial personal repositories. Note: we currently only have one official repository, the main repository. The official repositories are managed by the project lead and designated maintainers. Before a contribution is accepted into an official repository, it must pass the Contribution Criteria.

Unofficial repositories are personal forks that community members create to work on new features. All code development should occur in an unofficial repository. Once a change (bug fix or new feature) has completed, the contributor should push their changes to their github repository and then submit a pull request from their personal github repository to the appropriate official repository.

Developers also have the option of cloning an official repository and submitting a patch. This is recommended only for small changes or bug fixes. Contributors working on adding features or who submit many small changes are encouraged to use the github pull request approach.

Official repositories

The main repository is here: https://github.com/OpenKinect/libfreenect

There is currently a master branch and a Win32 branch for building out the Windows drivers.

In the future, we may add additional official repositories as forks for sub-projects that need integration before pushing to the main repository.

Before you start work

Before you start working on a contribution please familiarize yourself with this entire page as well as the project Policies.

If you want to contribute, you will need to install and use Git and will also need a GitHub account, which is free.

Developing a contribution

We recommend that you develop your code using a fork of the official repository you want to contribute to. Please see the github forking guide http://help.github.com/forking/ for details on how to fork the repository, clone, make changes, push your changes to your fork.

As you develop your code, keep in mind the Policies. If you intend to submit your code back to the OpenKinect Project, do not copy or include any code which is not under the appropriate license. Since we distribute under the Apache 2.0 and GPL v2 license, we require contributions to be under both of those licenses as well. If it is just Apache or just GPL then it won't work.

It would save the maintainers some time if you prepared your source code using the OpenKinect Source Header.

OpenKinect Source Header v1.0

 This file is part of the OpenKinect Project. http://www.openkinect.org
 
 Copyright (c) 2010 individual OpenKinect contributors. See the CONTRIB file 
 for details.
 
 This code is licensed to you under the terms of the Apache License, version 
 2.0, or, at your option, the terms of the GNU General Public License, 
 version 2.0. See the APACHE20 and GPL20 files for the text of the licenses, 
 or the following URLs:
 http://www.apache.org/licenses/LICENSE-2.0
 http://www.gnu.org/licenses/gpl-2.0.txt
 
 If you redistribute this file in source form, modified or unmodified, 
 you may:
 1) Leave this header intact and distribute it under the same terms, 
 accompanying it with the APACHE20 and GPL20 files, or
 2) Delete the Apache 2.0 clause and accompany it with the GPL20 file, or
 3) Delete the GPL v2.0 clause and accompany it with the APACHE20 file
 In all cases you must keep the copyright notice intact and include a copy 
 of the CONTRIB file.
 Binary distributions must follow the binary distribution requirements of 
 either License.

When you have a change ready to be committed to an official repository, it is time to submit your contribution.

Submitting a contribution

All contributions will be tracked through GitHub Issues. Contributors have two options:

  • Submit a github pull request from a forked repository [Preferred]
  • Manually add an issue and link to a patch file

(Submitting a pull request creates a linked issue.)

Logically separate changes should be submitted with separate contributions. Each contribution should include as few commits as possible, or ideally one. It is easier to evaluate small sets of changes for inclusion in the official repositories. This does not mean you should combine unrelated commits; rather, that unrelated changes should be a separate contribution.

If necessary, there are ways to combine separate commits into one commit. This should always be done in your local repository before pushing to a public repository.

Minimizing the number of commits also makes it easier to sign-off on your work.

Sign your work

We have implemented a simple procedure that ensures that the OpenKinect Project only accepts contributions that the contributor has the right to submit and that can be distributed under our License Policy. Every contribution must be signed-off by the contributor in the git commit message.

For example, if a pull request includes two commits, they must each include the sign-off in the commit message. Sign-off must be done for each commit, even if the contributor has signed-off previous contributions.

Sign-off means that for the contribution in question, the contributor can certify the statements in the Developer's Certificate of Origin (DCO), shown below:

 OpenKinect Developer's Certificate of Origin v1.0
 
 The OpenKinect Project distributes software under two licenses: 
 the Apache License v2.0 and the GNU General Public License v2.0
 (referred to as DISTRIBUTION LICENSES).
 
 By making a contribution to this project, I certify that:
 
 (a) The contribution was created in whole or in part by me and I have the 
     right to submit it under the terms of all DISTRIBUTION LICENSES; or
 
 (b) The contribution is based upon previous work that, to the best of my 
     knowledge, is covered under the terms of all DISTRIBUTION LICENSES or 
     under another license that permits me to submit the work under the terms of 
     all DISTRIBUTION LICENSES; or
 
 (c) The contribution was provided directly to me by some other person who 
     certified (a), (b), or (c) and I have not modified it.
 
 (d) I understand and agree that this project and the contribution are public 
     and that a record of the contribution (including all personal information
     I submit with it, including my sign-off) is maintained indefinitely and 
     may be redistributed consistent with this project or the open source 
     license(s) involved.


To sign-off a commit, the author of the code should include a line in the commit message that follows this exact template:

 Signed-off-by: Random J Developer <random@developer.example.org> (optional-pseudonym)


using his or her real name and a working email address. If the contributor desires, a pseudonym may be included at the end of the line in parenthesis, otherwise omit the pseudonym field and parenthesis.

This line can be automatically added by git if you run the git-commit command with the -s option.

By including this sign-off on the DCO, you represent that you are legally entitled to submit the contribution. Among other things, this protects the project and other contributors from a lawsuit from your employer if there is a question about the origin of a contribution. If you have any doubt whether your employer has a claim over the code that you wrote, it is your responsibility to check with and get authorization from your employer before you submit your contribution.

Forgetting to sign off after committing

Let's say that you have a bunch of commits you have already done, and want to make a merge request, but you have forgotten to sign off your commits. To fix this, start a new branch (assuming upstream is at origin/master):

   git checkout -b new-branch-name $(git merge-head origin/master)

Then cherry pick your commits from your old branch, with the -s option

   for ref in $(git rev-list --reverse ..old-branch-name); do git cherry-pick -s $ref; done

Optional: At this point, you could go back and clean up your commits (such as squashing "fixup" commits together with the commits they fix) with

  git rebase -i $(git merge-head origin/master)

And push the changes back to your Github repository

   git push github-remote-name new-branch-name

And make the merge request again, with this new branch.

To avoid this problem in the future, you can create a .git/hooks/commit-msg file, with the following contents:

#!/bin/sh
# Catch missing signoff

if ! grep -q '^Signed-off-by: ' "$1" ; then
    echo >&2 No Signed-off-by line.
    exit 1
fi

This will prevent commits unless they have a signoff line.

Evaluating contributions

When a contribution is submitted, a reviewer will review the it. When the review is complete, the reviewer will integrate the code into an official repository and include a line with the following this template:

 Reviewed-by: Random J Developer <random@developer.example.org> (optional-pseudonym)

This line indicates that the reviewer has found the contribution to be acceptable according to the Reviewer's Statement of Oversight, shown below:

 Reviewer's Statement of Oversight
 
 By offering my Reviewed-by: tag, I state that:  
 
   (a) I have carried out a technical review of this contribution to 
   evaluate its appropriateness and readiness for inclusion into 
   an official repository.
 
   (b) I have verified that all commits have been signed-off, or have 
   documented the contributor's desire for the sign-off to be added 
   on his or her behalf.
 
   (c) Any problems, concerns, or questions relating to the contribution
   have been communicated back to the submitter. I am satisfied
   with the submitter's response to my comments.
 
   (d) While there may be things that could be improved with this 
   submission, I believe that it is, at this time, (1) a worthwhile
   addition to the OpenKinect project, and (2) free of known  
   issues which would argue against its inclusion.
 
   (e) While I have reviewed the contribution and believe it to be 
   sound, I do not (unless explicitly stated elsewhere) make any 
   warranties or guarantees that it will achieve its stated  
   purpose or function properly in any given situation.

Adding the Review-by line is the last step before the contribution is integrated into an official repository. Congratulations! You're now a developer-contributor!

If a contribution doesn't pass review, don't be discouraged. Most likely there is a small change that needs to be made to bring it up to par. The community will work with you if you need help.