summaryrefslogtreecommitdiffstats
path: root/docs/contributing/gitreview.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/contributing/gitreview.rst')
-rw-r--r--docs/contributing/gitreview.rst199
1 files changed, 199 insertions, 0 deletions
diff --git a/docs/contributing/gitreview.rst b/docs/contributing/gitreview.rst
new file mode 100644
index 00000000000..b2608d11812
--- /dev/null
+++ b/docs/contributing/gitreview.rst
@@ -0,0 +1,199 @@
+.. _gitreview:
+
+*******************************
+Getting a Patch Reviewed
+*******************************
+
+This section describes how to get FD.io VPP sources reviewed and merged.
+
+Setup
+========
+
+If you don't have a Linux Foundation ID, `create one here. <https://identity.linuxfoundation.org/>`_
+
+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>`_
+
+`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."
+
+If you're on Ubuntu, install keychain:
+
+.. code-block:: console
+
+ $ sudo apt-get install keychain
+
+ssh keys
+-------------
+
+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.
+
+Create your public and private ssh key with:
+
+.. code-block:: console
+
+ $ ssh-keygen -t rsa
+ $ keychain
+ $ cat ~/.ssh/id_rsa.pub
+
+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**.
+
+.. _clone-ssh:
+
+Clone with ssh
+==============
+
+Clone the repo with:
+
+.. code-block:: console
+
+ $ git clone ssh://gerrit.fd.io:29418/vpp
+ $ cd vpp
+
+This will only work if the name of the user on your system matches your Gerrit username.
+
+Otherwise, clone with:
+
+.. code-block:: console
+
+ $ git clone ssh://<YOUR_GERRIT_USERNAME>@gerrit.fd.io:29418/vpp
+ $ cd vpp
+
+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.
+
+Git Review
+===========
+
+The VPP documents use the gerrit server, and git review for submitting and fetching patches.
+
+
+New patch
+-----------------
+
+When working with a new patch, use the following commands to get your patch reviewed.
+
+Make sure you have modified the correct files by issuing the following commands:
+
+.. code-block:: console
+
+ $ git status
+ $ git diff
+
+Then add and commit the patch. You may want to add a tag to the commit comments.
+For example for a document with only patches you should add the tag **docs:**.
+
+.. code-block:: console
+
+ $ git add <filename>
+ $ git commit -s
+
+The commit comment should have something like the following comment:
+
+.. code-block:: console
+
+ docs: A brief description of the commit
+
+ Type: Improvement (The type of commit this could be: Improvement, Fix or Feature)
+
+ A detailed description of the commit could go here.
+
+Push the patch for review.
+
+.. code-block:: console
+
+ $ git review
+
+If you are creating a draft, meaning you do not want your changes reviewed yet, do the following:
+
+.. code-block:: console
+
+ $ git review -D
+
+After submitting a review, reset where the HEAD is pointing to with:
+
+.. code-block:: console
+
+ $ git reset --hard origin/master
+
+Existing patch
+-----------------------
+
+The "change number" used below is in the URL of the review.
+
+After clicking an individual review, the change number can be found in the URL at "https://gerrit.fd.io/r/#/c/<*CHANGE_NUMBER*>/"
+
+To view an existing patch:
+
+.. code-block:: console
+
+ $ git review -d <change number>
+ $ git status
+ $ git diff
+
+.. caution::
+
+ If you have made changes and do "git review -d <change number>", your current
+ changes will try to be stashed so that the working tree can change to the review branch
+ you specified. If you want to make sure you don't lose your changes, clone another Gerrit
+ repo into a new directory using the cloning steps shown in :ref:`clone-ssh`, and perform
+ "git review -d <change number>" in this new directory.
+
+To modify an existing patch, make sure you modified the correct files, and apply the patch with:
+
+.. code-block:: console
+
+ $ git review -d <change number>
+ $ git status
+ $ git diff
+
+ $ git add <filename>
+ $ git commit --amend
+ $ git review
+
+When you're done viewing or modifying a branch, get back to the master branch by entering:
+
+.. code-block:: console
+
+ $ git reset --hard origin/master
+ $ git checkout master
+
+Patch Conflict Resolution
+-------------------------
+
+Two different patch conflict scenarios arise from time to
+time. Sometime after uploading a patch to https://gerrit.fd.io, the
+gerrit UI may show a patch status of "Merge Conflict."
+
+Or, you may attempt to upload a new patch-set via "git review," only to
+discover that the gerrit server won't allow the upload due to an upstream
+merge conflict.
+
+In both cases, it's [usually] fairly simple to fix the problem. You
+need to rebase the patch onto master/latest. Details vary from case to
+case.
+
+Here's how to rebase a patch previously uploaded to the Gerrit server
+which now has a merge conflict. In a fresh workspace cloned from
+master/latest, do the following:
+
+.. code-block:: console
+
+ $ git-review -d <*Gerrit change #*>
+ $ git rebase origin/master
+ while (conflicts)
+ <fix conflicts>
+ $ git rebase --continue
+ $ git review
+
+In the upload-failure case, use caution: carefully **save your work**
+before you do anything else!
+
+Rebase your patch and try again. Please **do not** re-download ["git
+review -d"] the patch from the gerrit server...:
+
+.. code-block:: console
+
+ $ git rebase origin/master
+ while (conflicts)
+ <fix conflicts>
+ $ git rebase --continue
+ $ git review
+