DevQuickstart

= OpenStack Bug Fixing Step-by-Step =

Step 1: Set Up Your Development Environment

 * 1.1) The easiest way to build a fully functional development environment is with DevStack. In order to use it, you will need a machine (or Vagrant box) running Ubuntu 11.10. If you've already got a machine up and running, skip to step 1.4. Otherwise, read on.
 * 1.2) At this point you need to create a local virtual machine running Ubuntu 11.10. A common method, if you have the capability to run VirtualBox, is to use Vagrant. Head over to https://github.com/openstack-dev/devstack-vagrant for further instructions.
 * 1.3) If you can't run VirtualBox or some other virtualization application locally, you'll need to look to the cloud! You can set up an account on Amazon EC2 or Rackspace Cloud to run a temporary machine.
 * 1.4) Follow the guide at http://devstack.org to get your environment up and running.
 * NOTE: If you prefer not to use devstack, you can still check out source code on your local machine and develop from there.

Step 2: Sign the CLA and Sign in to LaunchPad

 * 2.1) Head over to http://launchpad.net and click 'Log in / Register' in the top-right corner to sign up. Once you've created your account, you need to do a few more things
 * 2.2) Sign the OpenStack CLA. You can sign it electronically at http://wiki.openstack.org/CLA
 * 2.3) Add yourself to the Contributors wiki page. See the instructions at the top of this page: http://wiki.openstack.org/Contributors
 * 2.4) Join the openstack-cla launchpad group. To do this, navigate to https://launchpad.net/~openstack-cla and click 'Join the team' on the right side of the page. Your request will be forwarded to the core OpenStack developers, who can then approve your request. Keep in mind, you must have completed the first two steps for your membership to be approved. Once you have submitted your request to join the team, feel free to move on. Just keep in mind that you must be approved before you can submit any code!
 * NOTE: At this point, it would be a good idea to join the #openstack-dev IRC channel on Freenode. There are always developers around to help with code reviews or to answer any other general questions you may have. If you find that your request to join the openstack-cla team from step 3 is blocking your ability to submit code, feel free to ping someone in that chatroom!

Step 3: Claim a Bug

 * 3.1) The OpenStack projects keep all of their bug reports on LaunchPad. Follow one of the links below to see a list of open and unclaimed bugs for each specific project:
 * Nova Bugs
 * Glance Bugs
 * Swift Bugs
 * Keystone Bugs
 * Horizon Bugs
 * NOTE: If you're still a beginner with OpenStack, it might be a good idea to filter the bugs down to 'low-hanging-fruit'. Look for a link on the right to see this list.
 * 3.2) Once you've searched through the list and found something you want to work on, open up the full bug report, click the yellow edit button in the 'Assigned to' column then click 'Assign me' in the box that pops up. You should also set the status to 'In Progress'.

Step 4: Fix the Bug
Now that you've picked out what you're going to work on, head into your development environment and go crazy! We strongly suggest that you first write a failing test that reproduces the behavior detailed in the bug report. Core developers will end up asking for a test that verifies the fix when you get to the code review step, so you might as well take care of it up front. In order to run tests, look for the 'run_test.sh' shell script. It will run all of the tests for the project you are in and check for any style errors.

If you find you can't reproduce the bug from the details in the report, feel free to ask around. Several bugs pop up due to mis-configured environments or only apply in extremely specific situations. Here are the lists of core members for each project:


 * Nova: https://launchpad.net/~nova-core/+members#active
 * Glance: https://launchpad.net/~glance-core/+members#active
 * Swift: https://launchpad.net/~swift-core/+members#active
 * Keystone: https://launchpad.net/~keystone-core/+members#active
 * Horizon: https://launchpad.net/~horizon-core/+members#active

Step 5: Propose the Fix

 * 5.1) There is a bit more work to be done before you can propose your patch. First you need to install 'git-review'. This tool adds a 'review' command to git which helps with some bootstrapping of your repo and individual patches to work with our code review tool. The easiest way to get git-review is to use pip:


 * 5.2) Next you need to ensure your fix is in a single commit with a link to the bug in the commit message. In order to do that, we suggest that you run 'git rebase -i origin/master'. This will open an interactive editor in which you can 'squash' your commits together. This process also allows you to edit the commit message that will be sent with the review. Your fix can be automatically linked back to the bug on launchpad if you place a string like 'Fixes bug XXXXXX' in your commit message. If you have troubles with this step, please head to (http://wiki.openstack.org/GerritWorkflow) or just grab someone on IRC.
 * 5.3) Once you've installed git-review and cleaned up your patch, feel free to run 'git review'. A link to your review should be printed out to the screen. At this point you can move on to another bugfix! If you end up getting any feedback that you need to address, continue on to the next step
 * 5.4) Once you fix any code-related problems and you are ready to resubmit your review, you need to once-again squash your new commit(s) into one. Make sure you don't remove the 'Change-Id: ...' line from your commit message as that is the piece of information Gerrit uses to tie your subsequent patches together into one review. You can run the same command, 'git review', to push up your updated code.