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:
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 "email@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 firstname.lastname@example.org
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 “email@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.
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:
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
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 firstname.lastname@example.org:~jiyda/mediagoblin/jiydas-mediagoblin.git. To fix the issue, simply open the file .git/config file and change the url, from:
fetch = +refs/heads/*:refs/remotes/origin/*
url = git://gitorious.org/mediagoblin/mediagoblin.git
fetch = +refs/heads/*:refs/remotes/origin/*
url = email@example.com:~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.