Contents


Contribute your code to OpenStack

Comments

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
    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
    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:
      ./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
      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
      Main tab
      Figure 5. Arguments tab configuration
      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
      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
    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
    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
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.

Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

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