How to use git to contribute to a project (MediaGoblin)!

Today, I wanted to fix a small bug in an open source project called MediaGoblin. I am applying for Google Summer of Code and we are asked to make a small contribution. Even though fixing the bug itself did not take much time, uploading the changes took forever since this is my first time contributing to an open source project.  So here is a step by step guide on how I managed to do it.

How to contribute to a project in gitorious

MediaGoblin and many other open source projects are using a distributed version control system called git hosted on a social community website designed to make it easy to contribute to any project in there. In this case the host is gitorious.org.

Step 1: Generate a public SSH key

Gitorious uses SSH keys to establish a secure connection between your computer and gitorious. You will need to generate a public key and then add the key to your gitorious account.

First, you need to check for existing ssh keys. Run the Terminal and type:

cd ~/.ssh

If the output is “No such file or directory” you need to generate a new key. If not you can skip this part. Enter the code below by replacing the email with your email. When asked to enter a file name, just press enter. You will also be asked to enter a passphrase, chose a password and remember it, you will use it later.

ssh-keygen -t rsa -C "example@example.com"

The output should look like this

# Your identification has been saved in /home/you/.ssh/id_rsa.
# Your public key has been saved in /home/you/.ssh/id_rsa.pub.
# The key fingerprint is:
# 01:0f:f4:3b:ca:85:d6:17:a1:7d:f0:68:9d:f0:a2:db example@example.com

If you open id_rsa.pub it should contain your public key.

Step 2: Create a gitorius account and add your key

Create an account in gitorius. Once you have an account, you have to add your ssh key into your account. You can do that by replacing user by your username in https://secure.gitorious.org/~user/keys. Now, you can type in the search box the project you are interested in for example mediagoblin and browse their files.

Step 3: Configure git with your email and name

You should tell git what is your name and email. Run the terminal and execute each one of these commands with your info:

git config –global user.name “FirstName LastName”
git config –global user.email “example@example.com”

Step 3: Clone the project’s code

Gitorious makes it really easy to create your own clone of an existing public repository. Browse the project in gitorius for instance mediagoblin and click on Clone Repository.  You will have your own public repository in which you can add changes to it from your terminal.  Now, you need to clone the project locally and get your own copy of the code, copy the url of the main project from gitorious, it should look like the one below. Navigate to the folder you want to save the source code in and run:

git clone git://gitorious.org/mediagoblin/mediagoblin.git

This might take time depending on the size of the project. For mediagoblin and many other projects you would need to also install dependencies, you should look in the docs of the project. For mediagoblin, you can check here.

Step 4: Make your modifications

Here is the real part. Make any changes to the files and save them. You can run this command to see the changes you have made.

git status

To add one of the files you modified for committing, use:

git add path/to/file

Running git status again would show you the files that are ready to be committed.

Step 4: Commit the changes

Usually, in an open source project, you are making these changes to fix a specific bug or issue that you found or created in their bug tracking system. You should then create a branch based off of the project repository master branch, call it something like 444_the_bug_title, where 444 is the issue/bug’s number in the tracking system. To create a new branch and switched to it, run:

git checkout -b 444_the_bug_title

When you run:

git branch

You will see a list of the branches, and the branch with the * is the one you are working on now. You can create as many branches as you like, in case you are working on different bugs at a time.

Now, you are ready to commit, simply run

git commit

It will open a file in the default editor in which you need to write the commit message, the commit message should include the title, the issue number and a summary of the changes. Here is an example:

Added rtl language support

RTL languages like Arabic, Hebrew etc were displayed from left
to right. I fixed this by adding a function to check
whether the language of the locale is rtl and change the
direction of the html in "base.html" accordingly.

[Fixes #220]

Save it and exit. If you want to change the default editor run the following command by replacing myeditor with your editor of choice. I personally like emacs.

git config --global core.editor myeditor

Step 5: Push the changes to your public repository

Now, that you committed the changes, you need to make them public for others to see. You should run

git push origin 444_the_bug_title --set-upstream

You will be asked for the passphrase you made earlier.

You might get this error the first time you run the push command :

acer@acer-Aspire=5810T:~/mediagoblin $ git push origin master
fatal: protocol error: expected sha/ref, got '
The git:// protocol is read-only.

Please use the push url as listed on the repository page.

This problem occurs when the  .git/config file has the wrong url. You need to tell git where to find your public repository. Open your gitorious account and navigate to your public repository that you created earlier. Copy your SSH url, it should look like this git@gitorious.org:~jiyda/mediagoblin/jiydas-mediagoblin.git. To fix the issue, simply open the file .git/config file and change the url, from:

[remote “origin”]
fetch = +refs/heads/*:refs/remotes/origin/*
url = git://gitorious.org/mediagoblin/mediagoblin.git


[remote “origin”]
fetch = +refs/heads/*:refs/remotes/origin/*
url = git@gitorious.org:~jiyda/mediagoblin/jiydas-mediagoblin.git

Now, run the push command above and it should work. 🙂

Step 5: Let people know where did you upload the changes

If you open your gitorious account, you will find a new branch with your changes. You can share that url in the comment section under the issue you are working on. Explain what changes did you make and why do you think it’s the best approach. The commit url should look like : https://gitorious.org/~jiyda/mediagoblin/jiydas-mediagoblin/commit/4a4e4e4ae83d6ff3f09580238049e74444b01416.

That’s it! 🙂

Learning git for beginners:

I am following this online book, it is just perfect. You will learn all that you need to know about git.