How to begin contributing by tracking and fixing a bug from start to finish

image

This post originally appeared on Manishanker’s Blog. Manishanker is an undergraduate student from BITS Pilani, Goa who is OpenStacking in his free time.

My contribution : link

First of all lets answer the question who can contribute to Openstack. Anyone . Yes, anyone can contribute to Openstack. Whether you are interested in developing new feature in Openstack or in Documentation or in fixing Bugs , you are welcome. That’s how Open source projects work.

Lets answer another question. Why should anyone contribute to Openstack? The answer would be : To learn more about the project. By contributing you learn a lot of things. You are making the system better and helping others all over the world who use Openstack.

Let’s begin

This is where you should start. The link has all the information on How to contribute. All the commands used here are from that link. In case if you want more info please use the link provided in the beginning. My mentor suggested me to fix a Bug in Openstack. Bug can be a very small one like fixing a typo in the code message or it can be a critical one. Both are considered as contribution to Openstack. You are not fixing a typo error but you are fixing a bug in Openstack and making it better. I went with a very small bug in Sahara (obviously I don’t have adequate knowledge to fix a critical Bug but I made my contribution with what I can do) .I had to change all the instances in the code with the word "components" with "component(s)". Seems simple ? yes it is!

Where to begin?

Launchpad Account

Launchpad has all the information about bugs, overview etc. Get a launchpad account by registering here. Click on Openstack and you will be redirected to its main launchpad page. All the projects in Openstack, links to documentation, irc, mailing list etc can be found there.

Join Openstack Foundation

Fill out the details and join the foundation link

Log Into Gerrit Review System

Login here with your Launchpad account. This is where all the code reviews happen. Sign the Openstack individuals contributor License Agreement. And upload SSH keys .

Uploading SSH keys

Once you are logged into review.openstack.org, click here to upload your SSH keys. Follow this link to generate SSH keys. Once you have generated SSH keys, copy the Public key and upload it in review.openstack.org. Change to the directory where you have created your SSH keys, then list the contents of the folder and look for something ending in .pub which would be your public key.

Install git

I am using Ubuntu 12.04 LTS so you can begin with opening terminal 😉

Open Terminal (ctrl + alt +t ) and type "sudo apt-get install git" . After installing git, use this command to check for successful installation "git –version". If you can see the version of git, then it’s installed. Next set your username and email id . Type these commands in terminal.

git config --global user.name "Firstname Lastname"
git config --global user.email "[email protected]"

To check if you have configured properly check your configuration by using this command

git config --list

You would get information about your email id, username and other details. Learn more about git here

Install git-review

Install git review. Follow this link for different linux distros. In ubuntu it would be "sudo apt-get install git-review"

Lets track some Bugs

Login to your launchpad account and click on bugs. Out of all those bugs, low-hanging-fruit would be easy bugs to fix for beginners. Click on the low-hanging-fruit tag and select a bug which is easy to fix. Click on it, you can see its description, who reported it, which part of Openstack it is affecting and other details. Look for the Bugs which are Triaged and Confirmed and which are not assigned to any one. Triaged bugs will contain information on how to fix them in most of the cases. If you need any help understanding the bug or trying to find a fix for the bug, you can comment in the bug page or you can directly reach out to the reporter in IRC.

Once you have selected a bug and if you feel you could fix it assign it to yourself. This is the bug I assigned to myself. Next thing would be to clone the part of Openstack which has this bug.

I have cloned Sahara since the bug was in it. To clone a project to your local machine, open terminal and then use "git clone https://github.com/openstack/urproject.git" .You would get a message cloning into , receiving objects, receiving deltas then done. In my case, I would clone sahara project from github using this command : "git clone https://github.com/openstack/sahara.git". Change the directory to project " cd sahara". Next type the command "git review -s". This basically checks if you can login to Gerrit with your SSH keys. If your git username is different from your gerrit (review.openstack.org) username , use this command:

git config --global gitreview.username yourgerritusername

Your gerrit username would be the one in your profile tab in review.openstack.org. To verify your configuration use git config –list.

Once again verify your SSH keys , gerritusername in git config. If you get an error "We don’t know where your gerrit is.", you will need to add a new git remote. The url should be in the error message. Copy that and create the new remote.

git remote add gerrit ssh://<username>@review.openstack.org:29418/openstack/urproject.git

Next list the contents of the folder by using "ls -la" which would also list the hidden folders and files. You should see a .git hidden folder and .gitreview hidden file . Now try again "git review -s"

Everyone continuously make changes to the master branch in Github. To get the most updated code with all the changes use the following commands.

git remote update
git checkout master
git pull --ff-only origin master

To learn more about what origin, remote, master mean use this link. It has nice way of teaching about all the useful commands.

Important Steps

Create a Topic Branch

Since I am trying to fix a bug I would do git checkout -b "bug/1312908" where 1312908 is the bug id. Each bug is associated with a bug id which can be found in its page. You would see a message "switched to a new branch ‘bug/‘ ". Now use "git status" to check your branch.

Fixing the Bug

Now that we have everything in place and properly configured, lets fix the bug. To fix the bug in sahara all I had to do was follow the link Sergey gave in comments of the bug page which had all the occurrences of the word components. I opened those files and changed all the occurrences. Now if you remember we are currently in branch "bug/". Follow this link to know how to run test cases. You have to run unit tests to check if everything is working.

Fixed the bug, what to do next?
Next thing would be to commit the changes that you have made to fix the bug. This is where I made a mistake and had to commit twice. Please follow strictly the pattern that is given in the Commit messages so as to save your time.

Note that in most cases the Change-Id line should be automatically added by a Gerrit commit hook that you will want to install. See Project Setup for details on configuring your project for Gerrit. If you already made the commit and the Change-Id was not added, do the Gerrit setup step and run:

git commit --amend

The commit hook will automatically add the Change-Id when you finish amending the commit message, even if you don’t actually make any changes.
Make your changes, commit them, and submit them for review:

git commit -a
git review

Caution: Do not check in changes on your master branch. Doing so will cause merge commits when you pull new upstream changes, and merge commits will not be accepted by Gerrit.

Submitted for review, What’s next

Once you have submitted it appears on https://review.openstack.org and wait for the code reviewers to review. More info about the review process can be found here. Follow the comments and make necessary changes according to their comments. Once everything is correct it will be reviewed by core developers team and Jenkins will test all the components. You can check the status of gate jobs of your review at http://status.openstack.org/zuul/. After that it will be merged to the master branch.

This was my experience of first bug fix. I have learned a lot of new things by doing this. Hope this helps 🙂

Image credit: "finally got gail!" by Julochka

Manishanker Talusani
Latest posts by Manishanker Talusani (see all)