Contributing

From openmulticopter

The easiest way of contributing is to clone the openmulticopter git repository and/or to submit patches. We employ the integration-manager workflow. For description what it means you can check out Chapter 5-1 of Pro Git. In the following we describe the very basics on contributing and utilizing the workflow.

General documentation

There are tons of HOWTOs and tutorials on git usage, workflows and related stuff. Here a really small selection of them:

• Guides on Git from GitHub
• Git Cheat Sheet
• An example workflow
• Pro Git, a book about Git

Videos:

• Gitcasts (short introduction video tutorials on various git topics)
• Linus Torvalds on git (funny video, but not really a tutorial)
• Randal Schwartz: Git (good tutorial video/talk, but he talks pretty fast)
• Bart Trojanowski: Git the basics (very nice video tutorial)

Install git on your computer

First of all you should install git on your computer. On a Linux machine, for example on Debian or Ubuntu you can simply install the following package:

$ apt-get install git-core

To do that on other platforms follow one of the following tutorials:

• Getting and using Git on Windows
• Getting Git on a Mac

Tell Git who you are

You should tell Git who you are before pushing anything.

git config --global user.name "Your Real Name"
git config --global user.email "your@email-address"

The email address should be the same one you will use in the next step while creating the GitHub account so that GitHub can recognize which commits are yours.

Make an account on GitHub

Creating an account on the GitHub site should be really straight-forward. Just go to the webpage and create an account there. Do not forget to upload your ssh key there. Here is a good tutorial on providing your ssh key to GitHub. Otherwise you will not be able to access your repositories.

Creating a fork repository on GitHub

Now go to the openmulticopter master repository and press the Fork button. This will create a copy of the repository in your GitHub account.

Doing work and pushing back

Now go to the console on your machine and get your fork of the openmulticopter repository to your disk by typing:

$ git clone git@github.com:<yourname>/openmulticopter.git

Now you can go into that directory and make your changes. You can review what you changed by typing:

$ git status

or

$ git diff

Also a very useful tool here is gitk on Linux and gitx or gitnub on Mac.

If you are happy with your changes just add the files that contain your changes or are new by typing:

$ git add <file>

and afterwards commit them:

$ git commit

You will see an editor popping up, there you have to write what you have changed so that others can quickly see what you have done.

The commit is still only on your harddisk. You can still make more commits but they are not yet visible to the world. When you are happy with the commits you made you can push them back to the GitHub repository by typing:

$ git push

Now everyone can see your changes and you can notify us in the IRC channel or by using any other communication channel that we should review your changes and merge them into the master repository.

Staying up to date

First of all, do NOT use the Fork Queue feature of GitHub for that! It will break the commit history really badly, keep your fingers from that feature for now!

If you want to keep your copy of the repository up to date with the master repository you can do the following:

Add the master repository as a remote source of changes:

 $ git remote add masterrepo git://github.com/esden/openmulticopter.git

Now fetch the changes that are there but not on your machine:

 $ git fetch masterrepo

Merge the changes in the master repository into your repository:

 $ git merge masterrepo/master

And push the updated contents to your forked repository to GitHub:

 $ git push

Tips and tricks

A collection of small tips and tricks other openmulticopter developers are using.

.gitconfig candy

Here is an example additional settings for ~/.gitconfig file. There are some very useful aliasses to abbeviate the most often used git commands and some eye candy colors.

[user]
        name=Your Real Name
        email=your@email.address

[core]
        excludesfile = ~/.gitignore

[alias]
        br = branch
        co = checkout
        ci = commit
        di = diff
        st = status
        up = pull --rebase
        cp = cherry-pick

[color]
        branch = auto
        diff = auto
        status = auto

[color "branch"]
        current = yellow reverse
        local = yellow
        remote = green

[color "diff"]
        meta = yellow bold
        frag = magenta bold
        old = red bold
        new = green bold

[color "status"]
        added = yellow
        changed = green
        untracked = cyan

.gitignore candy

Example content for the .gitignore file located in your home directory:

*~
.DS_Store