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

Difference between revisions of "Code Integration"

From OpenKinect
Jump to: navigation, search
(Integration workflow)
Line 32: Line 32:
 
* Integrator pushes to main repo
 
* Integrator pushes to main repo
  
=== Integrator Instructions ===
+
== Development Story ==
  
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.  
+
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.
  
=== Developer Instructions ===
+
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.
 +
 
 +
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.

Revision as of 21:48, 21 November 2010

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

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.

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.