How To Contribute

Contents

How can I help?

Please join our communication forums:

  • Subscribe to OpenStack-dev mailing list.
  • When posting messages to the openstack-dev mailing list, prefix the subject with [compass].

If you're a developer

Bug fixing

You can start to contribute with bug fixing. Confirmed bugs are usually good targets. Here is the list of bugs that have been reported.

You can provide instruction on how to fix a certain bug. Or you can directly fix it: assign the bug to youself, set the status to IN PROGRESS, branch the code, implement the fix, and propose your change. Once your fix has been merged, come back and add a commit then check the status to FIX COMMITTED.

Housekeeping

Maitaining good code quality is a non-stopping work that share with all development team member. There are always several constant work you can help with. For instance, adding explaining comments in code, reducing pylint violations, increasing code coverage. Those are good ways to get involved, and it will let you to get familiar with different part of code.

Feature development

Once you are comfortable with the code, you can start to share your idea by contributing new feature. We use Openstack Launchpad Blueprints and Specs to track the design and implementation of significant features. By using blueprint, you can propose a deign and contain the sepcification.

To get start, you need to follow this process:

  • Register your bluepring in Launchpad by going to https://blueprints.launchpad.net/compass and clicking "Register a blueprint"
  • Git clone https://github.com/stackforge/compass-specs.git
  • You can find an example spec in specs/template.rst
  • Get it reviewed by submitting your patch using Gerrit
  • Assignee sets implementation status to "Implemented" when the work is completed

For more information, please see: https://wiki.openstack.org/wiki/Blueprints

Reviewing

Every patch submitted needs to get reviewed before it can be approved or merged. Any developer in compass team can be your reviewer. Before you add reviewer, you change needs to pass automated testing. When a new patch is submitted, Jenkins and Compass CI will run the project's tests on the patch. Once completed, Jenkins and Compass CI will report test result to gerrit in the form of a Verified: +/-1 vote. You will need one developer and one menager's reviews to be approved and merged.

For more information, please see: http://docs.openstack.org/infra/manual/developers.html#code-review

If you are a tester

We need you to make sure that Compass behaves correctly. Feel free to try compass and report any issue. For how to install compass, please see Try Compass for more information.

Developer guide of compass manual

Quick reference

Getting started

The purpose of this part is to walk you through the concepts and specificactions that should be understood before contributing the Compass.

Before you get into details of the project, a few steps need to be compeleted. Such as setting up a few account on required webstie, signing a contributor license agreement, uploading an ssh key, and installing git-review.

Account setup

First of all, you will need a Launchpad account, since this is how the Gerrit Code Review system will identify you. Then, do not forget to join The OpenStack Foundation which is free and required for all code contributors. Please make sure you use same email address as the one for code contributions, since this will need to match your preferred email address in Gerrit.

Visit https://review.openstack.org/ and click the "Sign In" link at the top-right corner of the page. Login with your Launchpad ID. The first time you login OpenStack's Gerrit, you will nee to select a unique username.

Every contributor needs to agree to the Individual Contributor License Agreement and provide contact information.

Setting up git configuration

Run these steps to set up the git configuration. Please ensure the email matches the one in your Gerrit contact information:

git config --global user.name "Firstname Lastname"
git config --global user.email "your_email@youremail.com"

To check your git configuration:

git config --list

You will also want to upload an SSH key to Gerrit at review.openstack.org, so that you will be able to commit changes for review later.

Installing git-review

Git-review is a git subcommand that handles all the details of working with Gerrit. Before you start work, make sure git-review has been installed.

On Ubuntu(12.04) or later, git-review is included in the distribution, so install it as any other package:

apt-get install git-review

On Fedora 16 and later, Red Hat Enterprise Linux, and CentOS 6.5 and later, you must enable the EPEL repository first, then install the package:

yum install git-review

All of git-review's interactions with gerrit are sequences of normal git commands. If you want to know more about what it is doing, just add -v to the options and it will print out all of the commands it is running.

Working on the project

Clone Compass:

git clone git://git.openstack.org/stackforge/compass-core.git

You may want to ask git-review to configure your project to bind with Gerrit. If you do not do it at this point, it will do so the first time you submit a patch. But you may want to do this ahead of time. To do so:

cd compass-core
git review -s

Git-review checks that you can log in to gerrit with your ssh key. It assumes that your gerrit/launchpad user name is the same as the current name. If the user name does not match, it asks you to enter your gerrit/launchpad user name. You can avoid that question by typing the following:

git config --global gitreview.username yourgerritusername

If you do not remember your Gerrit user name go to the settings page on gerrit to check it out (it is not your email address).

Development workflow

Working on bugs

Bug reports for the project are tracked on Launchpad at https://bugs.launchpad.net/compass. Contributor may review these reports regularly when looking for work to tackle.

When working on bugs, there are four aspects you need to notice:

  • When a bug is filed, it is set to "New" status. A "New" bug can be set to "Confirmed" once it has been reproduced and is confirmed as authentic.
  • Make sure the bug has been marked "In Progress" if it is assigned.
  • If information that caused bugs to be marked as "Incomplete" has been provided, see if more information is required and remind bug reporter if they have not responded after 2-4 weeks.
  • Check with assignee if the bug is still being worked on. If not, unassign it and mark it back to "Confirmed".

Once you find a bug that you are interested in, assign it to youself. When you submit a patch, please include the bug information in the commit message as reference so Gerrit can create a link to the bug. The following options are available:

Closes-Bug: #1234567 -- use 'Closes-Bug' if the commit is intended to fully fix and close the bug being referenced.
Partial-Bug: #1234567 -- use 'Partial-Bug' if the commit is only a partial fix and more work is needed.
Related-Bug: #1234567 -- use 'Related-Bug' if the commit is merely related to the referenced bug.

Working on specifications and blueprints

Compass project has a specs repository which is used to hold approved design specifications for feature and changes to the project.

You can find an example spec in specs/template.rst

Check the repository to learn about the organization.

git clone https://github.com/stackforge/compass-specs.git

Specifications are proposed by adding them to the specs/"release"directory and submit it for review. Launchpad blueprints were used to track the implementation of these significant features and changes in Compass. The implementation status of a blueprint can be found at the blueprint in Launchpad.

Compass-core structure

After you checkout the Compass project, go inside compass-core directory and take a look at the structure. Here we are going to briefly explain compass-core/compass, compass-core/conf and compass-core/misc.

  • Compass: All python code goes here.
  • Conf: These config files are used by compass to deploy clusters, not for compass service itself.
  • Misc: Contains miscellaneous config files used by system services such as ntp and apache. These services configs are modified specifically for compass service to use.

Testing Compass project

Before starting to work on the code, it is necessary to test if Compass code runs properly in your local environment. It is recommended to use tox the tun the unit tests.

It is suggested you install tox with pip:

[apt-get | yum] install python-pip
pip install tox

If you are using python 2.6, run following under compass-core directory:

tox -epy26

For python 2.7, run:

tox -epy27

The test result may return with report syas: "EnvironmentError: mysql_config not found". Sometimes mysql_config is missing on your system or the installer could not find it. Be sure mysql_config is really installed.

For CentOS 6.5 and later, run:

yum python-devel mysql-devel

For Ubuntu(12.04) or later, run:

apt-get install libmysqlclient-dev python-dev

Starting a change

Once your local repository is set up, you can start contribute.

Make sure you have the latest upstream changes:

git remote update
git pull origin

Once you are done with the changing, you need to run style checks and unit tests to make sure the code is still executable.

tox -epep8
tox -epy26

Committing a change

Git commit messages explain the chage in detail. If your changes are related to a blueprint or a bug, be sure to mention them in the commit message using the following syntax:

Implements: blueprint BLUEPRINT
Closes-Bug: ####### (Partial-Bug or Related-Bug are options)

Submitting a change for review

Once you have committed a change to your local repository, all you need to do to send it to Gerrit for code review:

git review

Updating a change

If you need to make additional changes, make and amend the changes to the existing commit. Leave the Change-ID the way it is. Gerrit knows this is an updated patch for an existing change.

git commit --amend
git review

Code review

When a new patch is uploaded to Gerrit, project's tests are run on the patch by Jenkins and Compass are run by Compass CI. Once completed the test result are reported to Gerrit in the form of a Verified: +/-1 vote.

If a change fails tests in Jenkins or Compass CI, please follow the steps below:

  • Jenkins and Compass CI leave comments with links to the log files for the test run. Follow those links and check out the output.It will include a console log.
  • Examine the console log to determine the cause of the error. If it is related to your change, go fix the problem and upload a new patchset.
  • It may be the case that the error is caused by non-deterministic reason like time out which is unrelated to your change. To re-run check, leave a comment on the review: "recheck compassci".

    Compass requires more than two positive reviews from core team to approve. You need to choose one reviewer from developers and the other from core reviewers. Once the core reviewer you chose believe it is ready, he or she will mrege your change.

    Here is the name list of Compass core team(listed alphabetically):

    • Core reviewer
      • Weidong Shao
      • Shuo Yang
    • Developer
      • Xicheng Chang
      • Sam Su
      • Xiaodong Wang
      • Grace Yu
      • Jerry Zhao
    Back to Top