From bcddab220f26c2036d7638b3fd4063541731818e Mon Sep 17 00:00:00 2001 From: andrew Date: Mon, 6 Aug 2018 17:40:31 -0400 Subject: docs: Cleaned up a little removed instructions for mac. docs: Updated section on using git-review Change-Id: I180f67e3478b57b1de03df95fc67a0cfdd44dfb5 Signed-off-by: andrew --- docs/gettingstarted/writingdocs/gitreview.rst | 111 +++++++++++++++++++++----- 1 file changed, 89 insertions(+), 22 deletions(-) (limited to 'docs') diff --git a/docs/gettingstarted/writingdocs/gitreview.rst b/docs/gettingstarted/writingdocs/gitreview.rst index 8eb8d071402..146b06f5c00 100644 --- a/docs/gettingstarted/writingdocs/gitreview.rst +++ b/docs/gettingstarted/writingdocs/gitreview.rst @@ -1,22 +1,32 @@ .. _gitreview: -*************************** +******************************* Merging FD.io VPP documents -*************************** +******************************* This section describes how to get FD.io VPP documents reviewed and merged. -Git Review -========== +Setup +======== -The VPP documents use the gerrit server and git review. +If you don't have a Linux Foundation ID, `create one here. `_ -Clone with ssh --------------- +With your Linux Foundation ID credentials sign into `Gerrit Code Review at gerrit.fd.io `_ + +`Install 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 -To get FD.io VPP documents reviewed the VPP repository should be cloned with ssh. + $ sudo apt-get install keychain -Use the following to setup you ssh key +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 @@ -24,50 +34,107 @@ Use the following to setup you ssh key $ keychain $ cat ~/.ssh/id_rsa.pub -Copy that key to the gerrit server. -Then clone the repo with: +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 `_, 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 it will ask if you want to add the Server Host Key to the list of known hosts. Type **yes** and hit enter. + +Git Review +=========== + +The VPP documents use the gerrit server and git review for submitting and fetching patches. + + New patch --------------- +----------------- -To get a new patch reviewed use the following: +When working with new patch use the following to get your patch reviewed. + +Make sure you have modified the correct files with: .. code-block:: console $ git status + $ git diff + +Then add and commit the patch. For documents we will add a tag **DOCS:** + +.. code-block:: console + $ git add - $ git commit -s + $ git commit -s -m "DOCS: " $ git review -If the patch is a draft use the following: +If you are creating a draft, meaning you do not want your changes reviewed yet, do the following: -.. note:: +.. code-block:: console $ git review -D - -To get back to the master: +After submitting a review, reset where the HEAD is pointing to with: .. code-block:: console $ git reset --hard origin/master - $ git checkout master Existing patch --------------- +----------------------- + +The "change number" used below is in the URL of the review. -To modify an existing patch: +After clicking an individual review, the change number can be found in the URL at "https://gerrit.fd.io/r/#/c//" +To view an existing patch: .. code-block:: console - $ git review -d + $ git review -d $ git status + $ git diff + +.. caution:: + + If you have made changes and do "git review -d ", 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 " 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 + $ git status + $ git diff + $ git add $ git commit --amend $ git review + +When you're done viewing or modifying a branch, get back to the master branch with: + +.. code-block:: console + + $ git reset --hard origin/master + $ git checkout master -- cgit 1.2.3-korg