321 lines
10 KiB
ReStructuredText
321 lines
10 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 `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`: http://docs.openstack.org/infra/manual/developers.html#account-setup
|
||
.. _`join the OpenStack Foundation`: http://openstack.org/join
|
||
.. _`Gerrit Workflow's account setup`: http://docs.openstack.org/infra/manual/developers.html#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:
|
||
|
||
.. code-block:: console
|
||
|
||
$ ssh-keygen –t rsa
|
||
|
||
You can optionally enter a password to enhance security.
|
||
|
||
View and copy your SSH key:
|
||
|
||
.. code-block:: console
|
||
|
||
$ 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:
|
||
|
||
.. code-block:: console
|
||
|
||
$ 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``:
|
||
|
||
.. code-block:: console
|
||
|
||
$ git config --global gitreview.username yourgerritusername
|
||
|
||
You can also save some time by entering your email and your name:
|
||
|
||
.. code-block:: console
|
||
|
||
$ 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:
|
||
|
||
.. code-block:: console
|
||
|
||
$ git clone git://git.openstack.org/openstack/zaqar.git
|
||
|
||
For information on how to set up the Zaqar development environment
|
||
see :doc:`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:
|
||
|
||
.. code-block:: console
|
||
|
||
$ 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:
|
||
|
||
.. code-block:: console
|
||
|
||
$ 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:
|
||
|
||
.. code-block:: console
|
||
|
||
$ 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:
|
||
|
||
.. code-block:: console
|
||
|
||
$ 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:
|
||
|
||
.. code-block:: console
|
||
|
||
$ git checkout -b TOPIC-BRANCH
|
||
|
||
If you are working on a blueprint, name your :samp:`{TOPIC-BRANCH}`
|
||
``bp/BLUEPRINT`` where :samp:`{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`: http://docs.openstack.org/infra/manual/developers.html#development-workflow
|
||
|
||
Common problems
|
||
^^^^^^^^^^^^^^^
|
||
|
||
#. You realized that you were working in master and you haven't made any
|
||
commits. Solution:
|
||
|
||
.. code-block:: console
|
||
|
||
$ git checkout -b newbranch
|
||
$ git commit -a -m "Edited"
|
||
|
||
If you already created the branch, omit the :option:`-b`.
|
||
|
||
You put all your changes to :samp:`{newbranch}`. Problem solved.
|
||
|
||
#. You realized that you were working in master and you have made commits to
|
||
master. Solution:
|
||
|
||
.. code-block:: console
|
||
|
||
$ 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 :samp:`{newbranch}`. Problem solved.
|
||
|
||
#. 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`_
|
||
|
||
.. _`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:
|
||
|
||
.. code-block:: console
|
||
|
||
$ git review
|
||
|
||
You will see the URL of your review page once it is successfully sent.
|
||
|
||
You can also see your reviews in :guilabel:`My Changes` in Gerrit. The first
|
||
thing to watch for is a ``+1`` in the :guilabel:`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 :guilabel:`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
|
||
:guilabel:`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
|
||
:guilabel:`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.
|
||
|
||
.. _`making a good commit message`: https://wiki.openstack.org/wiki/GitCommitMessages
|
||
.. _`squashing guide` : http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html
|