As OpenStack, the open source cloud software, gains support, more and more individuals and corporations will want to contribute to the OpenStack community. Bug reporting, blueprint engagement, and code reviews are just a few of the ways to contribute. This article offers step-by-step instructions for setting up your development environment and contributing your code to OpenStack.

Share:

Sheng Bo Hou, Software Engineer, IBM

Sheng Bo Hou is a software engineer on the IBM Open Standards and Open Source Team. Since he joined IBM in 2010, his focus has been on cloud computing standards efforts. To align with IBM's support of standards and integrating open source software and development, he is currently contributing to the OpenStack community with development ideas on bug reporting and fixing, blueprint engagements, and more.



07 March 2013

Also available in Chinese Russian

OpenStack is an Infrastructure as a Service (IaaS) cloud computing project that is free open source software released under the terms of the Apache License. The project is managed by the OpenStack Foundation, a non-profit corporate entity established in September 2012 to promote, protect and empower OpenStack software and its community.

Resources are managed through a dashboard that gives administrators control while empowering users to provision resources through a web interface. This article shows you how to set up an account, set up your development environment, and start contributing to OpenStack.

Step 1: Set up your account with online registration and key configurations

  1. Set up your Launchpad account. Launchpad is where OpenStack hosts all its projects. Go to the Launchpad login page to register using your email address and give yourself a convenient Launchpad ID. Then go to https://launchpad.net/~LaunchpadID to set up your OpenPGP key and upload your SSH public key using the instructions on the page. For example, my Launchpad id is houshengbo, so I go to https://launchpad.net/~houshengbo, as shown in Figure 1.
    Figure 1. Set up your OpenPGP key
    Example of my Launchpad using id houshengbo
  2. Set up your SSH account for Gerrit. OpenStack applies a code review process to guarantee the code quality. Go to the OpenStack code review page and login with your Launchpad account. Then go to https://review.openstack.org/#/settings/ssh-keys, and upload your SSH public key.
    Figure 2. Upload your SSH public key
    Upload your SSH public key

Step 2: Sign the CLA agreement

  1. If you haven't already, join The OpenStack Foundation. Use the same email address that you plan to use for code contributions. Your primary email address in your foundation profile needs to match your preferred email you will set later in your Gerrit contact information.
  2. Go to the Code Review page. Click the Sign In link at the top-right corner of the page. Log in to Launchpad using your Launchpad ID.
  3. Unless you are a U.S. Government Employee (see below), agree to the Individual Contributor License Agreement and provide contact information. Your full name and email address are public. This contact information can be updated later if needed, but make sure the primary email address always matches the one you set for your OpenStack Foundation membership.
  4. Join the OpenStack Contributors group. Membership is required to submit code changes.

If you work as an individual contributor, the above steps are sufficient. If you work on behalf of a corporation or US government, you will probably need to follow some additional internal approval processes that can differ from company to company. For detailed information, refer to Contributors License Agreement.


Step 3: Set up the local development environment

  1. Set up the Eclipse environment:
    1. Install Ubuntu 11.10 or 11.10+ with python.
    2. Install git: sudo apt-get install git.
    3. Install Eclipse.
    4. Install PyDev plugin for Eclipse.
      1. On the Eclipse window, click Help > Install New Software.
      2. Configure the python interpreter for Eclipse. In the Work with field, enter http://pydev.org/updates and click Add.
      3. Check PyDev.
      4. Click Next until you reach the Review Licences window. Accept the terms of the license and click Finish.
    5. Install EGit plugin for Eclipse.
      1. On the Eclipse window, click Help > Install New Software.
      2. In the Work with field, enter http://download.eclipse.org/egit/updates and click Add.
      3. Check Eclipse EGit under Eclipse Git Team Provider.
      4. Click Next until you reach the Review Licences window. Accept the terms of the license and click Finish.
  2. Set up the code base.
    • Using devstack:
      1. Open the terminal, go to a target directory and run the following to get the devstack code:
        git clone git://github.com/openstack-dev/devstack.git
      2. Create a file named localrc under the devstack directory just created. Find information on how to configure localrc on DevStack website.
      3. Run ./stack.sh. The default workplace is /opt/stack, which can be manually changed. When devstack runs successfully for the first time, you can find all the code under /opt/stack.
    • An alternative method is to download a specific project instead of cloning all the projects. Using the project Keystone as an example:
      1. Open the terminal, go to a target directory (e.g. /opt/stack) and run the following to get the keystone code:
        git clone https://github.com/openstack/keystone.git
      2. Import the project(s) into Eclipse: Run Eclipse and set the workspace to the directory saving all the projects(/opt/stack).
      3. Create the PyDev project: Click File > New > PyDev project. Give it the same name as the project, like keystone and click Finish.
      4. Synchronize the project with Egit: In Eclipse, right-click the project (keystone), click Team > Share project, then click Next and Finish.
      5. After the above steps, you should be able to see [keystone master] after your project name in Eclipse.

Run unit tests

  • Run all the unit tests for a project:
    1. Open a terminal and go to the project directory, for example, keystone.
    2. Run the command ./run_tests.sh. When asked if want to create a virtual environment, choose Y or N.
  • Test a single case:
    1. Open a terminal and go to the project directory, for example, keystone.
    2. Run the command ./run_tests.sh <file path>, for example, ./run_tests.sh /opt/stack/keystone/tests/test_backend.py.
  • Test a single case:
    1. Open a terminal and go to the project directory, for example, keystone.
    2. Run the command ./run_tests.sh <file path>:<class name>, for example, ./run_tests.sh /opt/stack/keystone/tests/test_backend.py:CommonHelperTests.
  • Test a single method:
    1. Open a terminal and go to the project directory, for example, keystone.
    2. Run the command ./run_tests.sh <file path>:<class name>.<method name>, for example:

      Click to see code listing

      ./run_tests.sh
      /opt/stack/keystone/tests/test_backend.py:CommonHelperTests.test_format_helper_raises_malformed_on_incomplete_format

      .

Run the OpenStack services

  • Run all the services by Devstack:
    1. Open a terminal and go to the devstack directory.
    2. Run the command ./stack.sh. In localrc, specify the services to be run, for example, ENABLED_SERVICES=key,c-api,c-vol,c-sch,mysql,rabbit.
    3. Run ./unstack.sh to shut down all the services.
    4. After ./stack.sh is successfully run for the first time, you can also run ./rejoin-stack.sh to run all the specified services.
  • Run the services in Eclipse. Using Keystone as an example:
    1. Set up a debug configuration for keystone in Eclipse. Right-click the script keystone—all under bin, click Debug as > Debug Configurations, as shown in Figure 3.
      Figure 3. Debug configuration
      Debug configuration
    2. Set up the debug configuration. Click the Arguments tab, choose Other for the working directory and enter ${workspace_loc:keystone}, as shown in Figure 4 and Figure 5.
      Figure 4. Main tab configuration
      Main tab
      Figure 5. Arguments tab configuration
      Arguments tab configuration
    3. Launch Keystone: Click the Debug button on the Debug Configuration window, or run it from the Debug/Run pull-down tool bar button, as shown in Figure 6.
      Figure 6. Launch Keystone services
      Launch Keystone services

Step 4: Set up local machine configuration

  • Set up git global configuration:
    1. Open a terminal.
    2. Run the command git config --global user.name "Firstname Lastname".
    3. Run the command git config --global user.email "your_email@youremail.com".
  • Install git-review tool:
    • For Ubuntu 12.04 or later, run the command sudo apt-get install git-review in a terminal.
    • For a version earlier then Ubunu 12.04, run sudo pip install git-review.
  • Configure your project to know about Gerrit:
    1. Open a terminal and go to the project directory, for example, keystone.
    2. Run the command git review -s. It will ask you to enter your gerrit username. Type in your Launchpad id and press enter.

Step 5: Demo of OpenStack Workflow

If you find an issue for OpenStack, register it as a bug. If you would like to add new features, register it as a blueprint. The modification you are going to add should be in a branch other than the master. Also, do not mix multiple bug fixings or blueprint developments in one branch. The following workflow shows an example of a bug fix in Keystone.

  1. Submit a bug for Keystone:
    1. Go to https://launchpad.net/keystone.
    2. Click Report a bug, then enter the summary and the required information.
    3. Click the button Submit bug report. This bug has a link: https://bugs.launchpad.net/keystone/+bug/1087674 and a bug number: 1087674.
    4. Assign this bug to yourself in the Assigned to column.
    Figure 7. Submit a bug for Keytsone
    Submit a bug for Keytsone
  2. Create a branch in keystone for this bug (branch name Bug1087674):
    1. Open a terminal and go to the keystone directory.
    2. Make sure keystone is in the master via git checkout master.
    3. Run the command git checkout -b Bug1087674.
  3. Modify the keystone code in the branch Bug1087674.
  4. Commit the code to Gerrit:
    1. Open a terminal and go to the keystone directory.
    2. Run the command git commit -a.
    3. Enter some comments. The first paragraph should be brief in one sentence; the second paragraph could be a detailed description (optional); if this branch fixes a bug or a blueprint, add Fixes Bug1087674 or Blueprint XXXX as the last paragraph.
    4. Run the command ctrl+o, press enter, and run ctrl+x.
    5. Run git review.
  5. Check the submitted patch:
    1. Go to https://review.openstack.org, and login with your Launchpad account.
    2. From the top horizontal navigator, click My > Changes and you can find the patch you submitted.
    3. Within this demo, the link is https://review.openstack.org/#/c/17673/. This patch can be reviewed by any user. Any developer can give comments.
    Figure 8. Review page of the submitted patch
    Review page of the submitted patch

Normally this is the procedure to submit a patch. But, what if Some developers added comments and you decide to change this branch? Here's an option:

  1. Open a terminal and go to the keystone directory.
  2. Go to the branch Bug1087674 via git checkout Bug1087674.
  3. Do further modification to this branch.
  4. Go to the keystone directory.
  5. Run the command git commit -a –amend. (Do not run git commit -a, otherwise there will be more than one commits submitted to Gerrit, and it is not recommended at all.)
  6. Modify the comments if possible.
  7. Run the command ctrl+o, press enter and run ctrl+x.
  8. Run git review.

After the patch has been submitted for the second time, there are two patch sets found in the link https://review.openstack.org/#/c/17673/ as shown in Figure 9.

Figure 9. History of patch sets
History of patch sets

Furthermore, what if the master branch has been changed while you were working on the branch Bug1087674? Here's what you can do:

  1. Open a terminal, and go to the master via git checkout master.
  2. Update the code with git pull origin master.
  3. Switch back to the branch via git checkout Bug1087674.
  4. Rebase the code via git rebase -i master.
  5. If there is no conflict, run the command git commit -a –amend and run git review.
  6. If there is a conflict, the terminal shows the file with conflicts.
  7. You can also find the conflicts in Eclipse because the file with conflicts is marked with red sign.
  8. Manually fix the conflicts.
  9. Continue to rebase, run the command git rebase —continue.
  10. Till the rebase is successful, run the command git commit -a –amend and run git review.

Resources

Learn

Get products and technologies

  • Evaluate IBM products in the way that suits you best: Download a product trial, try a product online, use a product in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement service-oriented architecture efficiently.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Cloud computing on developerWorks


  • Bluemix Developers Community

    Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.

  • developerWorks Labs

    Experiment with new directions in software development.

  • DevOps Services

    Software development in the cloud. Register today to create a project.

  • Try SoftLayer Cloud

    Deploy public cloud instances in as few as 5 minutes. Try the SoftLayer public cloud instance for one month.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Cloud computing
ArticleID=860523
ArticleTitle=Contribute your code to OpenStack
publish-date=03072013