How to contribute to Openstack

My first communication with the OpenStack community was on their IRC channel dedicated to Outreachy mentors, interns and general inquisitors (#openstack-opw on Freenode). Victoria Martinez de la Cruz (IRC nick vkmc on Freenode) who is the program organizer and a mentor helped me get started. She familiarized me with how OpenStack works, how the different components are organized and how the different projects work under OpenStack. Once I looked through the different projects (List of Projects), I finally decided to work on OpenStack Trove. Victoria familiarized me with trove and also helped me with setting up Devstack. She also helped me find an easy bug to start with (tagged as a low-hanging-fruit). Low-hanging-fruit bugs are bugs that are easy to fix, ideal for beginners to get familiar with the workflow. I then tried accessing Gerrit by following the instructions mentioned here. 

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 the given link. My mentor (vkmc) 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 Trove .

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 14.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 "your_email@youremail.com"

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.

Once you have selected a bug and if you feel you can fix it assign it to yourself. 

 Next thing would be to clone the part of Openstack which has this bug.

I have cloned Trove 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 <whateverproject>, receiving objects, receiving deltas then done. 

In my case, I cloned trove project from github using this command : "git clone https://github.com/openstack/trove.git". Change the directory to project " cd trove". 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.

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/<bugid>' ". Now use "git status" to check your branch.

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 same 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, Whats 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.

I finally managed to successfully merge my first patch! :D (the link to it) and learnt a lot about the review process, technical communication and having a critical perspective to writing code.

C++ Template Functions Explained

Let us assume that we are in the situation where we need to create a function that calculates the absolute value of a number.
When you have a number that is positive, then absolute value of the number is that same number, but if the number is negative, then the absolute value of the number is that number with sign changed.
So, the function, if you work with int data type would be like this:

int AbsolteValue( int nNumber)
{
  return (nNumber>0)? nNumber:-nNumber;
}

But, what if somebody needs the same function with double data type, instead of int? In that case, you can create a function like the following:

double AbsoluteValue( double dNumber)
{
return (dNumber>0)? dNumber:-dNumber;
}

In the way same, we can keep creating functions reactively to cover: float, long int, long long int, long double and so on.
There could also be a possibility when you don’t want to use the usual data types, but like to use your own custom data type with typedef.
We cannot possibly predict all data types that our function could potentially use. In those situations, “function templates” comes to rescue.

C++ Function Template Syntax

There are two acceptable syntaxes:

template <class TypeName1, class TypeName2, ...>

Or,

template <typename Typename1, typename TypeName2>

Now, the function could be like this:

tempalte<typename T>
T
AbsoluteValue( T tNumber)
{
return (tNumber>0)? tNumber: -tNumber;
}

So, the algorithm does not depend on data type used in code any more. The algorithm is implemented no matter what data type is used.
Now it is time to ask yourself, what do we get and what do we lose with this approach.
Well, we gain from point of generality and we lose from point of speed.
In other words, if you need to create faster solution for one data type, don’t use template.
But, if your goal is to create a function that will not care about data types, you should use templates.

C++ Function Template Example Program

The following example C++ program shows how you can use template.

#include <iostream>

using namespace std;

template<typename T>
T
AbsoluteValue(T tNumber)
{
 return (tNumber>0)? tNumber:-tNumber;
}

int
main( void)
{
 int nNumber1 =  7, 
     nNumber2 = -7;

 cout<<"Absolute value  of  "
     <<nNumber1<<"  = "
     <<AbsoluteValue(nNumber1)<<endl;

 cout<<"Absolute value of "
     <<nNumber2<<"  = "
     <<AbsoluteValue(nNumber2)<<endl;

 double dNumber1 = 7.0923, 
        dNumber2 =-7.0923;

 cout<<"Absolute value of"
     <<dNumber1<<"  = "
     <<AbsoluteValue(dNumber1)<<endl;

 cout<<“Absolute value of "
     <<dNumber2<<"  = "
     <<AbsoluteValue(dNumber2)<<endl;

 int iExit; cin>>iExit;

 return EXIT_SUCCESS;
}

The output for the above program will be the following:

Absolute value of 7 = 7
Absolute value of -7 = 7
Absolute value of 7.0923 = 7.0923
Absolute value of -7.0923 = 7.0923

As you see in the above example, it has only one function, but it will react to any data types.
As we have seen how we could use template functions to not care about data type, we could use the same trick with C++ classes.
If your C++ supports C11 standard, you can use variadic templates, which has the ability to use more parameters, something like combination of templates and functions of unknown number of arguments.