Contribution Process Overview
Step 1: Registration
This step describes end-to-end registration process so that you can start contributing to Openstack. Here are just a few ways of how you can become part of community:
- Report a bug / Apply a bug fix
- Blueprint Engagement
- Code Reviews
Registration Checklist:
Here is the registration checklist:
- GitHub
- Launchpad
- SSH Key
- Join the OpenStack Foundation
- Individual Member
- Gerrit Account (OpenStack Code Review)
- Sign Contributors License Agreement
- Individual
Registeration Process:
Setup Launchpad Account
Launchpad is where OpenStack hosts all of its projects. Go to the Launchpad login page to register using your full name, email address, and choose desired password. Your LaunchpadID will be autoselected for you with format of <FirstName>-<LastName>. Then go to https://launchpad.net/~LaunchpadID to upload your SSH public key using the instructions specified on the page.
Launcpad account is necessary for mutliple reasons:
Report bugs
Contribute code
Edit the wiki
Review code
Post to the mailing list
Access Jenkins site
Fill out information in RED BOX to create an account on Launchpad:
Upload and associate SSH keys to your Launchpad account:
Generate SSH keys using instructions from https://help.github.com/articles/generating-ssh-keys, if you don't have one. Copy and paste the contents of your SSH public key to associate it with your Lanchpad account:
Join the OpenStack Foundation
Join the foundation as an individual member. Complete the individual member application here: https://www.openstack.org/join/register/.
When signing up for Foundation Membership, make sure to give the same E-mail address you’ll use for code contributions, since the Primary Email Address in your Foundation Profile will need to match the Preferred Email you set later in your Gerrit contact information. Here, is the sample application form:
Gerrit Account (Openstack Code Review)
Visit https://review.openstack.org/ and click the Sign In link at the top-right corner of the page. Log in with your Launchpad ID.
Set up your SSH account for Gerrit. OpenStack applies a code review process to guarantee the code quality. Go to https://review.openstack.org/#/settings/ssh-keys, and upload your SSH public key.
Sign Contributors License Agreement (Corporate and Individual)
Agree to the Individual Contributor License Agreement and provide your contact information.
Your full name and E-mail address will be public (since they also appear in project commit logs) and the latter needs to match the user.email in your Git configuration. Make sure the primary E-mail address always matches the one you set for your OpenStack Foundation Membership–otherwise Gerrit will give you an error message and refuse to accept your contact information.
The other contact information (postal address, phone numbers) will be kept confidential and is only used as a fallback record in the unlikely event The OpenStack Foundation needs to reach you directly over code contribution related matters. This contact information can also be easily updated later if desired.
At this point, you should be registered as Openstack contributor and should be able to access your Launchpad account and Gerrit code review account.
Step 2: Setup Development Enviornment
Setting up development enviornment depends on what kind of OpenStack project you are working on, documentation or OpenStack services.
Note: This setup was tested on Ubuntu 12.04 with Python 2.7.
Setup for Documentation:
Let's look at how to setup development enviornment for OpenStack Manuals.
- Install Apache Maven, Git, and git-review:
$ sudo apt-get install maven git git-review |
- Get a copy of the docs source files:
$ git clone https://github.com/openstack/openstack-manuals.git |
- Switch directory to openstack-manuals:
cd openstack-manuals |
- Enter your Gerrit account information, this is only one time setup to configure git review on your system :
$ git review -s |
Setup for OpenStack services:
These tools are needed on your system, git, setuptools, pip, and gcc.
- Update apt-get:
sudo apt-get update |
- Installing git:
sudo apt-get install git |
- Installing setuptools:
sudo apt-get install python-setuptools |
- Installing Pip:
wget https://raw.github.com/pypa/pip/master/contrib/get-pip.py sudo python get-pip.py |
- Installing gcc:
sudo apt-get install gcc |
- Installing additional packages:
sudo apt-get install python-dev libevent-dev libxml2-dev libxslt1-dev libsasl2-dev libsqlite3-dev libssl-dev libldap2-dev libffi-dev |
- Make a clone of the code from OpenStack Github repository, for example, Keystone:
git clone http://github.com/openstack/keystone.git cd keystone |
- Enter your Gerrit account information, this is only one time setup to configure git review on your system :
$ git review -s |
Step 3: Applying a fix
- Making sure we have the latest updates from upstream:
$ git checkout master $ git pull --ff-only origin master |
- Create a branch for the bug that you are working on, for example, bug # 999999:
$ git checkout -b fix-for-999999 (or bug/999999) |
- Locate the issue and apply your fix
- Generate documentation artifacts
$ mvn clean generate-sources |
- Verify your changes in the generated HTML or PDF output looks good.
- Commit your changes
$ git commit -a # Add a header in commit message which must be less than 50 characters. # Add detailed description in commit message. # The description can consists of multiple lines, each line must be less than 80 characters. # Add bug, blueprint # from Launchpad with tag like "Closes-bug: #<Bug No.> |
- Request a review for your committed changes
$ git review |
- Gerrit creates a new review request for your changes:
Applying a fix to OpenStack Service (Keystone)
- Making sure we have the latest updates from upstream:
$ git checkout master $ git pull --ff-only origin master |
- Create a branch for the bug that you are working on, for example, bug # 999999:
$ git checkout -b fix-for-999999 (or bug/999999) |
- Apply fix for the issue and add unit tests, if needed.
- Run unit tests:
$ ./run_tests.sh |
Commit your changes:
$ git commit -a # Add a header in commit message which must be less than 50 characters. # Add detailed description in commit message. # The description can consists of multiple lines, each line must be less than 80 characters. # Add bug, blueprint # from Launchpad with tag like "Closes-bug: #<Bug No.> |
- Build committed changes locally by running tox:
$ tox |
- Request review for your committed changes:
$ git review |
Congratulations! You are now part of OpenStack community.