zaqar/doc/source/first_patch.rst

Your first patch

This section describes how to create your first patch and upload it to Gerrit for reviewing.

Create your contributor accounts and set up your code environment

Accounts setup

You will need to create a Launchpad account to login to the Gerrit review system dashboard. This is also useful for automatically crediting bug fixes to you when you address them with your code commits. You will also have to sign the Contributors License Agreement and join the OpenStack Foundation. It is a good idea to use the same email all of these accounts to avoid hooks errors.

Visit the Gerrit Workflow's account setup section in the wiki to get more information on setting up your accounts.

SSH setup

You are going to need to create and upload an SSH key to Gerrit to be able to commit changes for review. To create an SSH key:

$ ssh-keygen –t rsa

You can optionally enter a password to enhance security.

View and copy your SSH key:

$ less ~/.ssh/id_rsa.pub

Now you can upload the SSH key to Gerrit.

Git Review installation

Before you start working, make sure you have git-review installed on your system.

You can install it with the following command:

$ pip install git-review

Git-review checks if you can authenticate to Gerrit with your SSH key. It will ask you for your username. You can configure your Gerrit username so you don't have to keep re-entering it every time you want to use git-review:

$ git config --global gitreview.username yourgerritusername

You can also save some time by entering your email and your name:

$ git config --global gitreview.email "yourgerritemail"
$ git config --global gitreview.name "Firstname Lastname"

You can view your Gerrit user name in the settings page.

Project setup

Clone the Zaqar repository with the following git command:

$ git clone git://git.openstack.org/openstack/zaqar.git

For information on how to set up the Zaqar development environment see devref/development.environment.

Before writing code, you will have to do some configurations to connect your local repository with Gerrit. You will only need to do this your first time setting up the development environment.

You can set git-review to configure the project and install the Gerrit change-id commit hook with the following command:

$ cd zaqar
$ git review -s

If you get the error "We don't know where your Gerrit is", you will need to add a new git remote. The URL should be in the error message. Copy that and create the new remote. It looks something like:

$ git remote add gerrit ssh://<username>@review.openstack.org:29418/openstack/zaqar.git

In the project directory you have a hidden .git directory and a .gitreview file. You can view them with the following command:

$ ls -la

Making a patch

Pick or report a bug

You can start tackling some bugs from the bugs list in Launchpad. If you find a bug you want to work on, assign yourself. Make sure to read the bug report. If you need more information, ask the reporter to provide more details through a comment on Launchpad or through IRC or email.

If you find a bug, look through Launchpad to see if it has been reported. If it hasn't, report the bug, and ask for another developer to confirm it. You can start working on it if another developer confirms the bug.

Here are some details you might want to include when filling out a bug report:

• The release, or milestone, or commit ID corresponding to the software that you are running
• The operating system and version where you've identified the bug
• Steps to reproduce the bug, including what went wrong
• Description of the expected results instead of what you saw
• Portions of your log files so that you include only relevant excerpts

In the bug comments, you can contribute instructions on how to fix a given bug, and set the status to "Triaged".

You can read more about Launchpad bugs in the wiki.

Workflow

Make sure your repo is up to date. You can update it with the following git commands:

$ git remote update
$ git checkout master
$ git pull --ff-only origin master

Create a topic branch. You can create one with the following git command:

$ git checkout -b TOPIC-BRANCH

If you are working on a blueprint, name your {TOPIC-BRANCH} bp/BLUEPRINT where {BLUEPRINT} is the name of a blueprint in Launchpad (for example, "bp/authentication"). The general convention when working on bugs is to name the branch bug/BUG-NUMBER (for example, "bug/1234567").

Read more about the commit syntax in the Gerrit workflow wiki.

Common problems

1. You realized that you were working in master and you haven't made any commits. Solution:

   $ git checkout -b newbranch
   $ git commit -a -m "Edited"

   If you already created the branch, omit the -b.

   You put all your changes to {newbranch}. Problem solved.

2. You realized that you were working in master and you have made commits to master. Solution:

   $ git branch newbranch
   $ git reset --hard HEAD~x
   $ git checkout newbranch

   Where x is the number of commits you have made to master. And remember, you will lose any uncommitted work.

   You put your commits in {newbranch}. Problem solved.

3. You made multiple commits and realized that Gerrit requires one commit per patch. Solution:

   • You need to squash your previous commits. Make sure you are in your branch and follow squashing guide. Then fill commit message properly.

   You squashed your commits. Problem solved.

Design principles

Zaqar lives by the following design principles:

• DRY
• YAGNI
• KISS

Try to stick to these design principles when working on your patch.

Test your code

It is important to test your code and follow the python code style guidelines. See running_tests for details on testing.

Submitting a patch

Once you finished coding your fix, add and commit your final changes. Your commit message should:

• Provide a brief description of the change in the first line.
• Insert a single blank line after the first line.
• Provide a detailed description of the change in the following lines, breaking paragraphs where needed.
• The first line should be limited to 50 characters and should not end with a period.
• Subsequent lines should be wrapped at 72 characters.
• Put the 'Change-id', 'Closes-Bug #NNNNN' and 'blueprint NNNNNNNNNNN' lines at the very end.

Read more about making a good commit message.

To submit it for review use the following git command:

$ git review

You will see the URL of your review page once it is successfully sent.

You can also see your reviews in My Changes in Gerrit. The first thing to watch for is a +1 in the Verified column next to your patch in the server and/or client list of pending patches.

If the "Jenkins" user gives you a -1, you'll need to check the log it posts to find out what gate test failed, update your patch, and resubmit.

You can set your patch as a work in progress if your patch is not ready to be merged, but you would still like some feedback from other developers. To do this leave a review on your patch setting Workflow to -1.

Once the gate has verified your patch, other Zaqar developers will take a look and submit their comments. When you get two or more +2's from core reviewers, the patch will be approved and merged.

Don't be discouraged if a reviewer submits their comments with a -1. Patches iterate through several updates and reviews before they are ready for merging.

To reply to feedback save all your comments as draft, then click on the Review button. When replying to feedback, you as the patch author can use the score of 0. The only exception to using the score of 0 is when you discover a blocking issue and you don't want your patch to be merged. In which case, you can review your own patch with a -2, while you decide whether to keep, refactor, or withdraw the patch.

Professional conduct

The Zaqar team holds reviewers accountable for promoting a positive, constructive culture within our program.

If you ever feel that a reviewer is not acting professionally or is violating the OpenStack community code of conduct, please let the PTL know immediately so that he or she can help resolve the issue.