Code Integration

Open Kinect Repo Policy

In an effort to keep up with the additions from the community while keeping a clean and usable source history in git, we've established a policy on merges to the main repository. This integration policy will hopefully make it easy for us to find bug and figure out where new features come in, while also keeping conflicts with new and ongoing development to a minimum.

Workflows

Developer workflow

• Developer clones repository
• Developer makes a new branch to work on feature with. Master branch should be reserved for upstreams unless developer knows what theyare doing with git.
  • git checkout -b [new feature branch name] master
• Developer makes changes to feature branch, signing off on every commit.
• Developer submits feature branch via pull request or patch filed as project issue.
• Once patch is merged to main repo, developer updates from remote repo and merges main repo into their master.
• Developer then makes new branch off master, continues on new feature.
• If developer has another feature they have worked on between the time they have submitted, needed commits can be cherry picked to new branch.

Integration workflow

Whenever an integrator brings in a new commit, it should be rebased to the head of the master branch on the main repo. However, due to the volume of pull requests and patches we're receiving, this may not always be the case for pull requests. This workflow makes sure we maintain linearity in the main repo while also not changing code out from under developers

• Integrator receives pull request or patch
  • If pull request, integrator makes sure it is rebased.
    • If not rebased, and developer is in IRC channel, talk to developer there to have them properly rebase. If developer is not in IRC channel, integrator pulls to local repo and rebases. If conflicts arise, notify developer via pull request comment.
  • If patch, integrate on top. If conflicted, contact developer via github issue comments.
• Integrator merges patch into main branch. Should always come in at head if rebase was successful.
• Integrator pushes to main repo

Development Story

Introduction

So, you've decided you want to develop on an OpenKinect project. Yay! We need all the help we can get. As project maintainers, We want to make sure that everyone's help is both attributed and commited correctly, as well kept in line with everyone else that's trying to help. That's why we've created our development and integration workflows, listed above. We realize these lists are somewhat opaque to people not familiar with git or development using distributed systems, so this portion of the document is a plain-english explanation of how development of new features should work on OpenKinect repositories.

Before we begin, it's very worth getting up to speed on git at

http://progit.org

I'll be covering git operations here, but not going into too much detail. The Pro Git book site covers everything in hideous, yet readable and understandable detail.

This tutorial will also assume that you've created a github account and are using github for your repo storage. If you aren't, it is assumed you know what you're doing, so you can skip the github steps.

Starting Development

The first thing you'll do as a developer is make your own fork of our repository. For those familiar with other code versioning systems, this isn't as serious as it sounds. Forking is a core practice of git, since everyone has their own repo.

To fork on github, sign into your account, go to

https://www.github.com/OpenKinect/libfreenect

and hit the "Fork Repo" button. This will cause the current state of the repo to be copied to your account, and you will now have a libfreenect repo available to work on. Once this is done, open up a terminal and run:

git clone git@github.com:[your_account_name]/libfreenect.git

This will bring the git repo to your file system, and set up your repo as a remote named "origin". Unlike centralized versioning systems, git allows you to set up multiple repositories you can sync with. In our case, you'll want to sync with the main OpenKinect repo too. So, while your "origin" will be your fork of the OpenKinect repo, you'll want to add the main OpenKinect repo as another remote. This can be done by running:

git remote add org-repo git://github.com/OpenKinect/libfreenect.git

in the repo clone you just made. Now if you run

git remote show

You'll see you have two remotes

• origin - Your own fork of our main repo
• org-repo - The main repo

You will have read/write access to the origin remote, but only read access to the org-repo remote. This means you can push changes to your own copy of the repo, but can only read changes from the main repo. Changes to the main repo have to be made by the repo integrator, which we'll talk about later.

Keeping up to date with the main repo

Now then, you'll want to have a branch in your repo that's kept up with the latest changes from the org-repo remote. This is how you will be able to integrate changes made by other people into your work, and what you will need to base your changes off of when you submit changes to us. For now, we'll call this branch "upstream". So, do a

git branch upstream master

This will make a branch called upstream that's based off your current master, and since your current master is cloned from your repo, which was forked from the org-repo, these should still match. However, to make sure, run

git remote update

You should see git try to get updates from origin and org-repo. This means it's checking both of those remote repositories for any changes, and downloading them to their respective remote sandboxes. Doing a remote update doesn't change any of your local branches, it just changes what your repo knows about where the remote repos are and what updates they have. If you see there are changes with the remote repository, you can do

git merge org-repo/master upstream

Which tells your repository to merge what's in the main repo's master branch to your local upstream branch. This will keep you up to date with everyone else's changes.

Making your own changes

Once you've made sure you're got a place that's up to date with the upstream, it's time to start making changes. First off, you'll want to make a branch off of upstream:

git checkout -b [feature-branch-name] upstream

I'm not going to cover the process of how commits work here, as that's covered quite well in other basic git tutorials. Also, please make sure to read about how to sign off on your commits at the Contributing Code page.

However, there's one thing we require that probably doesn't come 'til later chapters in the git book. We always want your changes to be on top of the upstream changes. So, for instance, let's say you're ready to start a new feature, and the commit chain of the upstream repo look like

A -> B -> C

So, C is the current latest change in the upstream repo. You start making commits on top of this in your feature branch, and get something that looks like

A -> B -> C -> D -> E

So upstream was at C, and you added commits D and E. However, while you're doing your work, other people have submitted their finished work, and it's come into the upstream. So the next time you do

git remote update
git merge org-repo upstream

Upstream now looks like

A -> B -> C -> F -> G

Which means your branch and upstream now differ by two commits, respectively. You have commits D and E, it has commits F and G. Since the upstream repo should be the reference repo, we want to get your commits up on top of what's on the upstream repo. This is done by an operation called "rebasing", because we want to change the "base" of your D and E commits from commit C of the upstream repo to commit G. With your feature branch currently checked out, this is done via the command

git rebase upstream

This peels your commits off of your branch, finds the common ancestor (commit C), so it starts at

A -> B -> C

merges in commits from the upstream, so we have

A -> B -> C -> F -> G

then starts replaying your commits on top of that, so we get

A -> B -> C -> F -> G -> D

Now, if there's a conflict in D, it'll stop at this point, as you to fix it, and tell you how to continue or stop the process. Otherwise, it'll keep going, and we end up with:

A -> B -> C -> F -> G -> D -> E

Which is what the integrator would like to see when getting your commits.

Getting your changes integrated

Check out Contributing Code to see how to get your changes integrated.