8fc1efaab9
These docs contain information on how to make the first contributions to Zaqar and how to make the first review in Gerrit for Zaqar to the developer's manual. Change-Id: I291ad85d735a3a096a36afa7650a08a37dbb4e89
228 lines
8.6 KiB
ReStructuredText
228 lines
8.6 KiB
ReStructuredText
..
|
||
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||
not use this file except in compliance with the License. You may obtain
|
||
a copy of the License at
|
||
|
||
http://www.apache.org/licenses/LICENSE-2.0
|
||
|
||
Unless required by applicable law or agreed to in writing, software
|
||
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||
License for the specific language governing permissions and limitations
|
||
under the License.
|
||
|
||
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 the `Gerrit Workflow's account setup`_ section in the wiki
|
||
to get more information on setting up your accounts.
|
||
|
||
.. _Launchpad: http://launchpad.net/
|
||
.. _Gerrit: http://review.openstack.org/
|
||
.. _`Contributors License Agreement`: https://wiki.openstack.org/wiki/How_To_Contribute#Contributor_License_Agreement
|
||
.. _`join the OpenStack Foundation`: http://openstack.org/join
|
||
.. _`Gerrit Workflow's account setup`: https://wiki.openstack.org/wiki/Gerrit_Workflow#Account_Setup
|
||
|
||
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 enchance security.
|
||
|
||
View and copy your SSH key::
|
||
|
||
$ less ~/.ssh/id_rsa.pub
|
||
|
||
Now you can `upload the SSH key to Gerrit`_.
|
||
|
||
.. _`upload the SSH key to Gerrit`: https://review.openstack.org/#/settings/ssh-keys
|
||
|
||
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 your for your username. You can configure your Gerrit username so you don't have to
|
||
keep re-entering it everytime 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`_.
|
||
|
||
.. _`settings page`: https://review.openstack.org/#/settings/
|
||
|
||
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 :doc:`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.
|
||
|
||
.. _`bugs list in Launchpad`: https://bugs.launchpad.net/zaqar
|
||
.. _`Launchpad bugs`: https://wiki.openstack.org/wiki/Bugs
|
||
|
||
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.
|
||
|
||
.. _`Gerrit workflow`: https://wiki.openstack.org/wiki/Gerrit_Workflow
|
||
|
||
Design principles
|
||
#################
|
||
|
||
Zaqar lives by the following design principles:
|
||
|
||
* `DRY`_
|
||
* `YAGNI`_
|
||
* `KISS`_
|
||
|
||
.. _`DRY`: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
|
||
.. _`YAGNI`: https://en.wikipedia.org/wiki/YAGNI
|
||
.. _`KISS`: https://en.wikipedia.org/wiki/KISS_principle
|
||
|
||
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 :doc:`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 devs 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.
|
||
|
||
.. _`making a good commit message`: https://wiki.openstack.org/wiki/GitCommitMessages
|