3 *******************************
4 Getting a Patch Reviewed
5 *******************************
7 This section describes how to get FD.io VPP sources reviewed and merged.
12 If you don't have a Linux Foundation ID, `create one here. <https://identity.linuxfoundation.org/>`_
14 With your Linux Foundation ID credentials sign into `Gerrit Code Review at gerrit.fd.io <https://gerrit.fd.io/r/login/%23%2Fq%2Fstatus%3Aopen>`_
16 `Install git-review, <https://www.mediawiki.org/wiki/Gerrit/git-review>`_ which is a "command-line tool for Git / Gerrit to submit a change or to fetch an existing one."
18 If you're on Ubuntu, install keychain:
20 .. code-block:: console
22 $ sudo apt-get install keychain
27 To get FD.io VPP documents reviewed the VPP repository should be cloned with ssh. You should be logged into Gerrit Code Review as noted above.
29 Create your public and private ssh key with:
31 .. code-block:: console
35 $ cat ~/.ssh/id_rsa.pub
37 Copy **all** the contents of the public key (id_rsa.pub) output by the above **cat** command. Then go to your `SSH Public keys settings page <https://gerrit.fd.io/r/#/settings/ssh-keys>`_, click **Add Key ...**, paste your public key, and finally click **Add**.
46 .. code-block:: console
48 $ git clone ssh://gerrit.fd.io:29418/vpp
51 This will only work if the name of the user on your system matches your Gerrit username.
53 Otherwise, clone with:
55 .. code-block:: console
57 $ git clone ssh://<YOUR_GERRIT_USERNAME>@gerrit.fd.io:29418/vpp
60 When attempting to clone the repo Git will prompt you asking if you want to add the Server Host Key to the list of known hosts. Enter **yes** and press the **Enter** key.
65 The VPP documents use the gerrit server, and git review for submitting and fetching patches.
71 When working with a new patch, use the following commands to get your patch reviewed.
73 Make sure you have modified the correct files by issuing the following commands:
75 .. code-block:: console
80 Then add and commit the patch. You may want to add a tag to the commit comments.
81 For example for a document with only patches you should add the tag **docs:**.
83 .. code-block:: console
88 The commit comment should have something like the following comment:
90 .. code-block:: console
92 docs: A brief description of the commit
94 Type: Improvement (The type of commit this could be: Improvement, Fix or Feature)
96 A detailed description of the commit could go here.
98 Push the patch for review.
100 .. code-block:: console
104 If you are creating a draft, meaning you do not want your changes reviewed yet, do the following:
106 .. code-block:: console
110 After submitting a review, reset where the HEAD is pointing to with:
112 .. code-block:: console
114 $ git reset --hard origin/master
117 -----------------------
119 The "change number" used below is in the URL of the review.
121 After clicking an individual review, the change number can be found in the URL at "https://gerrit.fd.io/r/#/c/<*CHANGE_NUMBER*>/"
123 To view an existing patch:
125 .. code-block:: console
127 $ git review -d <change number>
133 If you have made changes and do "git review -d <change number>", your current
134 changes will try to be stashed so that the working tree can change to the review branch
135 you specified. If you want to make sure you don't lose your changes, clone another Gerrit
136 repo into a new directory using the cloning steps shown in :ref:`clone-ssh`, and perform
137 "git review -d <change number>" in this new directory.
139 To modify an existing patch, make sure you modified the correct files, and apply the patch with:
141 .. code-block:: console
143 $ git review -d <change number>
151 When you're done viewing or modifying a branch, get back to the master branch by entering:
153 .. code-block:: console
155 $ git reset --hard origin/master
156 $ git checkout master
158 Patch Conflict Resolution
159 -------------------------
161 Two different patch conflict scenarios arise from time to
162 time. Sometime after uploading a patch to https://gerrit.fd.io, the
163 gerrit UI may show a patch status of "Merge Conflict."
165 Or, you may attempt to upload a new patch-set via "git review," only to
166 discover that the gerrit server won't allow the upload due to an upstream
169 In both cases, it's [usually] fairly simple to fix the problem. You
170 need to rebase the patch onto master/latest. Details vary from case to
173 Here's how to rebase a patch previously uploaded to the Gerrit server
174 which now has a merge conflict. In a fresh workspace cloned from
175 master/latest, do the following:
177 .. code-block:: console
179 $ git-review -d <*Gerrit change #*>
180 $ git rebase origin/master
183 $ git rebase --continue
186 In the upload-failure case, use caution: carefully **save your work**
187 before you do anything else!
189 Rebase your patch and try again. Please **do not** re-download ["git
190 review -d"] the patch from the gerrit server...:
192 .. code-block:: console
194 $ git rebase origin/master
197 $ git rebase --continue