docs/gettingstarted/writingdocs/gitreview.rst

   1 .. _gitreview:
   2
   3 *******************************
   4 Merging FD.io VPP documents
   5 *******************************
   6
   7 This section describes how to get FD.io VPP documents reviewed and merged.
   8
   9 Setup
  10 ========
  11
  12 If you don't have a Linux Foundation ID, `create one here. <https://identity.linuxfoundation.org/>`_
  13
  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>`_
  15
  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."
  17
  18 If you're on Ubuntu, install keychain:
  19
  20 .. code-block:: console
  21
  22     $ sudo apt-get install keychain
  23
  24 ssh keys
  25 -------------
  26
  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.
  28
  29 Create your public and private ssh key with:
  30
  31 .. code-block:: console
  32
  33     $ ssh-keygen -t rsa
  34     $ keychain
  35     $ cat ~/.ssh/id_rsa.pub
  36
  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**.
  38
  39 .. _clone-ssh:
  40
  41 Clone with ssh
  42 ==============
  43
  44 Clone the repo with:
  45
  46 .. code-block:: console
  47
  48     $ git clone ssh://gerrit.fd.io:29418/vpp
  49     $ cd vpp
  50
  51 This will only work if the name of the user on your system matches your Gerrit username.
  52
  53 Otherwise, clone with:
  54
  55 .. code-block:: console
  56
  57     $ git clone ssh://YOUR_GERRIT_USERNAME@gerrit.fd.io:29418/vpp
  58     $ cd vpp
  59
  60 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.
  61
  62 Git Review
  63 ===========
  64
  65 The VPP documents use the gerrit server and git review for submitting and fetching patches.
  66
  67
  68 New patch
  69 -----------------
  70
  71 When working with new patch use the following to get your patch reviewed.
  72
  73 Make sure you have modified the correct files with:
  74
  75 .. code-block:: console
  76
  77     $ git status
  78     $ git diff
  79
  80 Then add and commit the patch. For documents we will add a tag **DOCS:**
  81
  82 .. code-block:: console
  83
  84     $ git add <filename>
  85     $ git commit -s -m "DOCS: <COMMIT_MESSAGE>"
  86     $ git review
  87
  88 If you are creating a draft, meaning you do not want your changes reviewed yet, do the following:
  89
  90 .. code-block:: console
  91
  92     $ git review -D
  93
  94 After submitting a review, reset where the HEAD is pointing to with:
  95
  96 .. code-block:: console
  97
  98     $ git reset --hard origin/master
  99
 100 Existing patch
 101 -----------------------
 102
 103 The "change number" used below is in the URL of the review.
 104
 105 After clicking an individual review, the change number can be found in the URL at "https://gerrit.fd.io/r/#/c/<CHANGE_NUMBER>/"
 106
 107 To view an existing patch:
 108
 109 .. code-block:: console
 110
 111     $ git review -d <change number>
 112     $ git status
 113     $ git diff
 114
 115 .. caution::
 116
 117     If you have made changes and do "git review -d <change number>", your current
 118     changes will try to be stashed so that the working tree can change to the review branch
 119     you specified. If you want to make sure you don't lose your changes, clone another Gerrit
 120     repo into a new directory using the cloning steps shown in :ref:`clone-ssh`, and perform
 121     "git review -d <change number>" in this new directory.
 122
 123 To modify an existing patch, make sure you modified the correct files, and apply the patch with:
 124
 125 .. code-block:: console
 126
 127     $ git review -d <change number>
 128     $ git status
 129     $ git diff
 130
 131     $ git add <filename>
 132     $ git commit --amend
 133     $ git review
 134
 135 When you're done viewing or modifying a branch, get back to the master branch with:
 136
 137 .. code-block:: console
 138
 139     $ git reset --hard origin/master
 140     $ git checkout master