A blog for developers who wants to get started with contributing to OpenStack projects.
This is the second blog in the series of Outreachy Internship blogs. I’m publishing a new blog every 2nd week for the next 3 months. The prompt of this week is to write about some open source jargons where I struggled. (I know I’m publishing it late!)
I remember when I was submitting my first patch, hmm it was not easy though! If you are starting a new journey, you will find that there is a lot to learn. The same happened with me too, I got introduced to many new open-source jargons every single day during the outreachy contribution period. Yup! I’m still figuring out new terms daily.
I’m writing this blog just to put everything in one place for those who want to start contributing to OpenStack. This is basically a “Getting started guide for OpenStack contribution”. You might find so many links in there, which is going to be helpful for sure :) So, let’s start with learning a little about OpenStack.
What is OpenStack?
OpenStack is a cloud operating system that controls large pools of computing, storage, and networking resources throughout a data centre, all managed and provisioned through APIs with common authentication mechanisms.
It’s a software package that provides a cloud platform for public and private cloud. They mainly focus on Iaas(Infrastructure as a Service). As a Cloud Administrator, you can use a command-line or web-based dashboard provision, control, and automate OpenStack resources.
*OpenStack is on a mission to produce a ubiquitous and most secure Open Source Cloud Computing platform. Also, which is easy to use, simple to implement, interoperable between deployments, works well at all scales and meets the needs of users and operators of both public and private clouds. Read more about OpenStack and its vision.*
OpenStack is open source & recognized for its security
OpenStack built from a set of microservices that combined into different setups based on actual needs. These services provide REST APIs for their users, to make usage of the APIs easier it is possible to use SDKs.
The following diagram provides a high-level overview of some OpenStack core services and their relationship with each other.
Image source: https://www.openstack.org/
The list of OpenStack components, Client tools and Development tools is so long. If you want to read more details about their services, check the links below:
How can you contribute?
You can contribute in any form, whether you are interested in developing some new features in OpenStack, in documentation, review code or in fixing Bugs. You are welcome!
Your contribution must be something that accomplishes OpenStack mission.
Why should anyone contribute to OpenStack?
- To learn more about the OpenStack projects
- Expand and learn more your skills
- Build connections with amazing developers
- Propose or fix anything which annoys you while researching on OpenStack :/
There are a few steps that every new contributor should follow to getting ready to contribute:
- Join mailing lists
- Get an IRC client
- Configure accounts on Launchpad, Gerrit, and sign the ICLA.
Join mailing lists
You can subscribe to public mailing lists from here to stay updated with all the OpenStack announcements, future development and community events details.
Get an IRC Client and Join
IRC (Internet Relay Chat) is one of the main communication channels for open source projects. You can freely join a channel that suits your interests if you are looking for help or interested in contributing.
To use IRC you need an IRC client. There are many client applications available that provide IRC functionality like HexChat, KiwiIRC, IRCCloud and more. You just need to do some research as per your browser and system. Also,
- If you are got introduced to IRC first time, please check this https://docs.openstack.org/contributors/common/irc.html
- If you are looking to join OpenStack IRC channels and meetings, you can check this https://wiki.openstack.org/wiki/IRC
- If you want to learn more about Internet Relay Chat (IRC) application then I find this as a great resource https://www.geeksforgeeks.org/internet-relay-chat-irc/
Getting ready to contribute:
So you have decided to contribute to OpenStack project. You can go through the below steps to configure accounts and the rest of the project setups. You need to create an Ubuntu One Account account that you will use to authenticate for Launchpad and Gerrit accounts.
Become a team member
Here to setup your Open InfraStructure Foundation account, follow this link for step by step details. https://docs.openstack.org/contributors/common/accounts.html
Setup and Learn Git
You can go through this link to learn more about git installation in your system and commit message structure. https://docs.openstack.org/contributors/common/git.html
Configuring Task Tracker Account
OpenStack currently uses two task tracker platforms Launchpad and StoryBoard for different projects. They soon are moving from the bug tracking software Launchpad to StoryBoard.
You can go through the below link to setup an account on any one of those as per your project choice.
Configuring Gerrit Code Review Account:
Before moving to the Gerrit account setup, a little about Gerrit- Gerrit is a web-based code review tool integrated with Git and built on top of Git version control system (helps developers work together and maintain the history of their work). It allows merging changes to the Git repository when you are done with the code reviews.
One thing I want to mention here is that Gerrit uses concepts of changes rather than pull requests. To learn about Gerrit workflow, you can check this link.
OpenStack community uses Gerrit to review codes, documentation, infrastructure changes and CI configurations. To sign up for it:
- Go to OpenStack’s Gerrit page https://review.opendev.org/
- Click sign in, you will be asked for a username. You can enter the same username here too.
Note: From here on out when you sign into Gerrit, you’ll be prompted to enter your Launchpad login info. This is because Gerrit uses it as an OpenID single sign on.
Now the next step here is to Sign the Openstack individual’s contributor License Agreement.
- Go to Gerrit’s setting.
- Click the New Contributor Agreement link and sign the agreement.
You need to sign this to contribute code & documentation. You will not be able to push patches to Gerrit without this.
The last step here is, setting the SSH Key. To add the SSH Keys into your Gerrit account, you need to generate it first. Follow this link to generate the ssh key. Now to import it into your Gerrit account:
- Go to Gerrit’s SSH Public Keys settings.
- Click the ‘Add Key’ button.
- Paste the public key into the Add SSH Public Key text box and click Add.
Git review Installation
You need to install
git-review . Open your terminal and type:
pip install git-review for macOS. Follow this for to check the command for different systems- https://docs.openstack.org/contributors/common/setup-gerrit.html#git-review
P.S. I would suggest using the same email and username for all account setup, that would be easy for you.
That’s a lot of information. You can now prepare yourself for the next steps.🥤 So, let’s move :)
To propose changes in the Git repository
- Start by cloning the repo or setting up the development environment with DevStack
- Remote update
- Create branch
- Running unit tests
- Curate a commit on that branch
- Do a git review
Start by cloning the repo or setting up DevStack
You can start contributing to the OpenStack project just by cloning the repository into your system or you can use DevStack to bring up a complete OpenStack environment for development. However, it is advisable to only run DevStack on servers or virtual machines that are dedicated to this purpose. You can run DevStack on the virtual machine using VirtualBox with Ubuntu.
There are some projects(python-manilaclient, manila and more) that don’t require setting up the whole environment, you can just clone the repo, add your changes, run tests on it and submit it for review. 🚀
Cloning the repo:
- To clone a project to your local machine, open the terminal and type
git clone <openstack-project-url>.
- Go to your installed project directory by
- You need to do
git review -d.This command sets up the necessary remote hosts and commits hooks to enable pushing changes to Gerrit. This basically checks if you can log in to Gerrit with your SSH keys.
- Git review assumes the user you’re running it as is the same as your Gerrit username. If your git username is different from your Gerrit (review.openstack.org) username, you can tell it by setting this git config setting:
git config --global gitreview.username <username>. Verify your username once again, using
git config -list.
- If you are hitting some error like “We don’t know where your gerrit is, please manually create a remote names ‘gerrit’ and try again. There you need to do
git remote add gerrit <your-repo-url>.Here
<your-repo-url>is the last link you got in the error message. (ssh://
. . .git)
- Now do
git review -dagain. This should work now. Yay!
Setting up DevStack
This is a whole different and a big topic. You can go through these links, to run devstack. You might hit some issues during this setup, in that case, make use of IRC channel.
Once you are done with the above steps, which is to set up the project into your local machine. You can move on to the next step!
Once you cloned the repo, before creating any branches and making your changes, make sure to get the latest upstream changes with the following commands:
git remote update git checkout master git pull --ff-only origin master
To create your development branch into the repo. It is a good practice to create a new branch with a bug number for each patch than to work from master.
Let’s suppose you are working on bug number #1898318, you can create a new branch with the name “bug/1898318”. You need to run this command:
git checkout -b bug/1898318
To check your branch, run this command:
Running unit tests
This is the most important step. You need to run unit tests, to check if everything is working properly before submitting it for review.
To run the unit test you are going to run tox. So you need to install the tox package here:
sudo pip install tox . You can** follow this** to learn more about unit tests. Also, you can do
sudo tox to run all the tests serially.
Curate a commit
You might be done with your fixes so you need to commit it. To commit your changes all you need to run is:
git commit -a --amend
This will open up a nano editor, write your commit message and for the best practice add only 80 char per line. Follow this guide for the commit message structure.
Time to submit your changes for review:
git review to push your changes for review.
git review is a command-line tool. This is a little bit different from what we use on GitHub with that PR. It is a specific tool that allows us to send some patches into OpenStack review system. Also,
git-review is a tool that helps to submit git branches to Gerrit for review.
*Note: When you are submitting the first patch into the project make sure to do*
git review -d* to initialize this into your project.*
Once you are done with it, all you need to do is be patient, don’t expect your first patch approval will be fast and do consider time zone difference.
I have already added the important links for you, but here are some-
Main openstack contributor guide: https://docs.openstack.org/contributors/code-and-documentation/index.html
Development workflow: https://docs.openstack.org/charm-guide/latest/making-a-change.html
That’s it. I hope that you find this helpful. See you next week :)