michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: edit of gerrit tutorial

Browse source 
Change-Id: I3f5831d5e41968c5ce43cc1042565f7677025caa
Signed-off-by: L.S. Cook <leonax.cook@intel.com>
Signed-off-by: Leona <lsc@hackeress.com>
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This commit is contained in:
Leona 2015-09-23 10:37:31 -07:00 • committed by Anas Nashif
commit c98560f783
1 changed files with 57 additions and 59 deletions
Download patch file Download diff file Expand all files Collapse all files

112
doc/collaboration/code/gerrit.rst
View file

@ -26,26 +26,26 @@ Make sure to subscribe to the `mailing list`_ by filling out the
.. _mailing list: foss-rtos-collab@lists.01.org
Follow the steps available at :ref:`access_source` for information about how to access the source
code using GIT and Gerrit.
code using Git and Gerrit.
Gerrit is a review system, and as such, assigns the following roles to
users:
* Submitter: Submit changes for consideration, review other code
changes and make recommendations for acceptance or rejection voting
* **Submitters**: May submit changes for consideration, review other code
changes, and make recommendations for acceptance or rejection by voting
+1 or -1, respectively.
* Maintainers: Approve or reject changes based upon the feedback of
the reviewers voting +2 or -2, respectively.
* Builder: Used for the build automation infrastructure.
* **Maintainers**: May approve or reject changes based upon feedback from
reviewers voting +2 or -2, respectively.
* **Builders**: May use the build automation infrastructure.
A comprehensive walkthrough of Gerrit is beyond the scope of this
document. There are plenty of resources available on the Internet. A
good summaries can be found here:
`<https://wiki.iotivity.org/how_to_use_gerrit>`_
`<https://gerrit-review.googlesource.com/Documentation/user-review-ui.html>`_
A comprehensive walk-through of Gerrit is beyond the scope of this
document. There are plenty of resources available on the Internet. Good
summaries can be found here:
For more detailed information visit:
`<http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/intro-quick.html>`_
* `How to use Gerrit <https://wiki.iotivity.org/how_to_use_gerrit_>`_
* `Gerrit User Review <https://gerrit-review.googlesource.com/Documentation/user-review-ui.html_>`_
For more detailed information visit: `Gerrit Documentation <http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/intro-quick.html_>`_
Submitting a Change
@ -53,17 +53,17 @@ Submitting a Change
Currently, Gerrit is only one method to submit a change for review.
Before you submit, please ensure each of your commits conform with the
coding and contribution guidelines of the project. Directions for
building the source code are out of the scope of this document. Please
refer to the :ref:`quick_start`.
Before submitting, please ensure each commit conforms with coding
and contribution guidelines. Directions for building the source code
are beyond the scope of this document. Please see the :ref:`quick_start`
for further detail.
When a change is ready for submission, Gerrit requires that the
change be pushed to a special branch. The name of this special branch
contains a reference to the final branch where the code should reside
contains a reference to the final branch where the code should reside,
once accepted.
For the |project|, the special branch is called refs/for/master .
For the |project|, the special branch is called :literal:`refs/for/master` .
1. Push the current local development branch to the gerrit server, type:
@ -71,7 +71,7 @@ For the |project|, the special branch is called refs/for/master .
$ git push origin HEAD:refs/for/master
If the command is executed correctly, the output should look similar to
If the command executes correctly, the output should look similar to
this:
.. code-block:: bash
@ -90,8 +90,8 @@ For the |project|, the special branch is called refs/for/master .
2. Add reviewers to your change.
a. To Define the list of reviewers via the command line at code
submission time. Add *%r=reviewer@project.org* to the command. For
a. To specify a list of reviewers via the command line, add
*%r=reviewer@project.org* to your push command. For
example:
.. code-block:: bash
@ -132,25 +132,24 @@ Reviewing Using Gerrit
little more explanation.
* Add: This button allows the change submitter to manually add names of
people who should review this change; type a name and the system
* **Add**: This button allows the change submitter to manually add names of
people who should review a change; start typing a name and the system
will auto-complete based on the list of people registered and with
access to the system. They will be notified by email that you are
requesting their input.
* Abandon: This button is only available to the submitter, allowing
the committer to abandon this change and get no more work done on
it.
* **Abandon**: This button is available to the submitter only; it allows a
committer to abandon a change and remove it from the merge queue.
* Change-ID: This is an ID generated by Gerrit (or system). This is
* **Change-ID**: This ID is generated by Gerrit (or system). It becomes
useful when the review process determines that your commit(s) have to
be redone. You can upload a new version and if the same Change-ID
be amended. You may submit a new version; and if the same Change-ID
header (and value) are present, Gerrit will remember it and present
it as another version of the same change.
* Status: Currently, the change is in review status, as indicated by
the “Needs Code-Review” in the upper left corner. The list of
Reviewers will all emit their opinion voting +1 if they agree to the
* **Status**: Currently, the example change is in review status, as indicated
by “Needs Code-Review” in the upper-left corner. The list of
Reviewers will all emit their opinion, voting +1 if they agree to the
merge, -1 if they disagree. Gerrit users with a Maintainer role can
agree to the merge or refuse it by voting +2 or -2 respectively.
@ -159,7 +158,7 @@ Signed-off-by line. Visit
`your gerrit page <https://oic-review.01.org/gerrit/#/dashboard/self>`_,
to check the progress of your requests.
Click on a request and the history tab shows you the feedback.
Click on a request and the history tab displays feedback.
.. figure:: figures/gerrit02.png
:scale: 75 %
@ -170,25 +169,25 @@ Click on a request and the history tab shows you the feedback.
Viewing Pending Changes
***********************
1. Find all the pending changes by clicking on the
:menuselection:`All --> Changes` link in the upper left corner or
1. Find all pending changes by clicking on the
:menuselection:`All --> Changes` link in the upper-left corner, or
directly at:
`<https://oic-review.01.org/gerrit/#/q/project:forto-collab>`_
If you collaborate in multiple projects, you may wish to limit the
branch through the search bar in the upper right side.
If you collaborate in multiple projects, you may wish to limit searching to
the specific branch through the search bar in the upper-right side.
Add the filter *project:forto-collab* to limit the visible changes only
to those of the forto-collab project.
Add the filter *project:forto-collab* to limit the visible changes to
only those from the forto-collab project.
2. List all current changes you submitted or those changes in need of
your input by clicking on :menuselection:`My --> Changes` or going to:
`<https://oic-review.01.org/gerrit/#/dashboard/self>`_
2. List all current changes you submitted, or list just those changes in need
of your input by clicking on :menuselection:`My --> Changes` or going to:
`Your Dashboard <https://oic-review.01.org/gerrit/#/dashboard/self_>`_
Reviewing a Change
******************
1. Click on a the link for incoming or outgoing review, such as
1. Click on a link for incoming or outgoing review, such as
*“This is test #1”* shown in this figure:
.. figure:: figures/gerrit03.png
@ -199,7 +198,6 @@ Reviewing a Change
2. The details of the change and its current status are loaded:
.. figure:: figures/gerrit04.png
:scale: 75 %
:alt: Detailed View of a Change in Gerrit
@ -210,23 +208,23 @@ Reviewing a Change
From left to right:
* **The state:** Displays the current status of the change. In the
example the status reads: +l Needs Code-Review.
* **Status:** Displays the current status of the change. In the
example below, the status reads: +l Needs Code-Review.
* **Reply:** Click on this button after reviewing to add a final
review message and a score, -1, 0 or +1.
* **Patch Sets:** If multiple revisions of a patch exist, this button
allows navigation between the revisions to see the changes. By
default, the most recent revision is presented.
enables navigation among revisions to see the changes. By default,
the most recent revision is presented.
* **Download:** This button brings up another window with multiple
options to download or checkout the current changeset. The button on
the right copies the line to your clipboard. You can easily paste it
into your git interface to work with the patch as you prefer.
3. Underneath the commit information, a list shows the files that have
been changed by this patch:
3. Underneath the commit information, the files that have been changed by
this patch are displayed:
.. figure:: figures/gerrit05.png
:scale: 75 %
@ -234,8 +232,8 @@ Reviewing a Change
Observe the list of the files changed by the patch at the bottom.
4. Click on a filename to start reviewing it. Select the code base to
differentiate against. The default is Base and it will generally be
4. Click on a filename to review it. Select the code base to differentiate
against. The default is :diff: Base and it will generally be
what is needed.
.. figure:: figures/gerrit06.png
@ -270,7 +268,7 @@ Reviewing a Change
Shows how to add a comment in the comparison window.
7. After adding the comment it is saved as a draft.
7. After adding the comment, it is saved as a draft.
.. figure:: figures/gerrit09.png
:scale: 75 %
@ -278,12 +276,12 @@ Reviewing a Change
Shows a comment saved as a draft.
8. Once reviewing all the files of the change is complete, click the
8. After reviewing all files and recommending your changes, click the
green up arrow at the top right to return to the main change page. Click
the reply button, write some final comments and submit your score for
the patch set. Click post to submit the review of each reviewed file as
the reply button, write some final comments, and submit your score for
the patch set. Click post to submit the review of each reviewed file, as
well as your final comment and score. Gerrit sends an email to the
change submitter and all listed reviewers. Finally, it logs the review
change-submitter and all listed reviewers. Finally, it logs the review
for future reference. All individual comments are saved as Draft until
the post button is clicked.