docs/developer-guide/getting-started-with-git-and-gerrit.rst

   1 Getting started with Git and Gerrit
   2 ===================================
   3
   4 Overview of Git and Gerrit
   5 --------------------------
   6
   7 Git is an opensource distributed version control system (dvcs) written
   8 in the C language and originally developed by Linus Torvalds and others
   9 to manage the Linux kernel. In Git, there is no central copy of the
  10 repository. After you have cloned the repository, you have a functioning
  11 copy of the source code with all the branches and tagged releases, in
  12 your local repository.
  13
  14 Gerrit is an opensource web-based collaborative code review tool that
  15 integrates with Git. It was developed at Google by Shawn Pearce. Gerrit
  16 provides a framework for reviewing code commits before they are accepted
  17 into the code base. Changes can be uploaded to Gerrit by any user.
  18 However, the changes are not made a part of the project until a code
  19 review is completed. Gerrit is also a good collaboration tool for
  20 storing the conversations that occur around the code commits.
  21
  22 The OpenDaylight source code is hosted in a repository in Git.
  23 Developers must use Gerrit to commit code to the OpenDaylight
  24 repository.
  25
  26 .. note::
  27
  28     For more information on Git, see http://git-scm.com/. For more
  29     information on Gerrit, see https://code.google.com/p/gerrit/.
  30
  31 Setting up a Gerrit account
  32 ---------------------------
  33
  34 1. Using a Google Chrome or Mozilla Firefox browser, go to
  35    https://git.opendaylight.org/gerrit
  36
  37 The main page shows existing Gerrit requests. These are patches that
  38 have been pushed to the repository and not yet verified, reviewed, and
  39 merged.
  40
  41 .. note::
  42
  43     If you already have an OpenDaylight account, you can click **Sign
  44     In** in the top right corner of the page and follow the instructions
  45     to enter the OpenDaylight page.
  46
  47 .. figure:: ./images/Sign_in.jpg
  48    :alt: Signing in to OpenDaylight account
  49
  50    Signing in to OpenDaylight account
  51
  52 1. If you do not have an existing OpenDaylight account, click **Account
  53    signup/management** on the top bar of the main Gerrit page.
  54
  55 The **WS02 Identity Server** page is displayed.
  56
  57 .. figure:: ./images/Gerrit_setup.jpg
  58    :alt: Gerrit Account signup/management link
  59
  60    Gerrit Account signup/management link
  61
  62 1. In the **WS02 Identity Server** page, click **Sign-up** in the left
  63    pane.
  64
  65 There is also an option to authenticate your sign in with OpenID. This
  66 option is not described in this document.
  67
  68 .. figure:: ./images/sign-up.jpg
  69    :alt: Sign-up link for Gerrit account
  70
  71    Sign-up link for Gerrit account
  72
  73 1. Click on the **Sign-up with User Name/Password** image on the right
  74    pane to continue to the actual sign-up page.
  75
  76 .. figure:: ./images/signup_image.jpg
  77    :alt: Sign-up with User Name/Password Image
  78
  79    Sign-up with User Name/Password Image
  80
  81 1. Fill out the details in the account creation form and then click
  82    **Submit**.
  83
  84 .. figure:: ./images/form_details.jpg
  85    :alt: Filling out the details
  86
  87    Filling out the details
  88
  89 You now have an OpenDaylight account that can be used with Gerrit to
  90 pull the OpenDaylight code.
  91
  92 Generating SSH keys for your system
  93 -----------------------------------
  94
  95 You must have SSH keys for your system to register with your Gerrit
  96 account. The method for generating SSH keys is different for different
  97 types of operating systems.
  98
  99 The key you register with Gerrit must be identical to the one you will
 100 use later to pull or edit the code. For example, if you have a
 101 development VM which has a different UID login and keygen than that of
 102 your laptop, the SSH key you generate for the VM is different from the
 103 laptop. If you register the SSH key generated on your VM with Gerrit and
 104 do not reuse it on your laptop when using Git on the laptop, the pull
 105 fails.
 106
 107 .. note::
 108
 109     For more information on SSH keys for Ubuntu, see
 110     https://help.ubuntu.com/community/SSH/OpenSSH/Keys. For generating
 111     SSH keys for Windows, see
 112     https://help.github.com/articles/generating-ssh-keys.
 113
 114 For a system running Ubuntu operating system, follow the steps below:
 115
 116 1. Run the following command::
 117
 118     mkdir ~/.ssh
 119     chmod 700 ~/.ssh
 120     ssh-keygen -t rsa
 121
 122 1. You are prompted for a location to save the keys, and a passphrase
 123    for the keys.
 124
 125 This passphrase protects your private key while it is stored on the hard
 126 drive. You must use the passphrase to use the keys every time you need
 127 to login to a key-based system::
 128
 129     Generating public/private rsa key pair.
 130     Enter file in which to save the key (/home/b/.ssh/id_rsa):
 131     Enter passphrase (empty for no passphrase):
 132     Enter same passphrase again:
 133     Your identification has been saved in /home/b/.ssh/id_rsa.
 134     Your public key has been saved in /home/b/.ssh/id_rsa.pub.
 135
 136 Your public key is now available as **.ssh/id\_rsa.pub** in your home
 137 folder.
 138
 139 Registering your SSH key with Gerrit
 140 ------------------------------------
 141
 142 1. Using a Google Chrome or Mozilla Firefox browser, go to
 143    https://git.opendaylight.org/gerrit.
 144
 145 1. Click **Sign In** to access the OpenDaylight repository.
 146
 147 .. figure:: ./images/Sign_in.jpg
 148    :alt: Signin in to OpenDaylight repository
 149
 150    Signin in to OpenDaylight repository
 151
 152 1. Click your name in the top right corner of the window and then click
 153    **Settings**.
 154
 155 The **Settings** page is displayed.
 156
 157 .. figure:: ./images/Gerrit_settings.jpg
 158    :alt: Settings page for your Gerrit account
 159
 160    Settings page for your Gerrit account
 161
 162 1. Click **SSH Public Keys** under **Settings**.
 163
 164 2. Click **Add Key**.
 165
 166 3. In the **Add SSH Public Key** text box, paste the contents of your
 167    **id\_rsa.pub** file and then click **Add**.
 168
 169 .. figure:: ./images/SSH_keys.jpg
 170    :alt: Adding your SSH key
 171
 172    Adding your SSH key
 173
 174 To verify your SSH key is working correctly, try using an SSH client to
 175 connect to Gerrit’s SSHD port::
 176
 177     $ ssh -p 29418 <sshusername>@git.opendaylight.org
 178     Enter passphrase for key '/home/cisco/.ssh/id_rsa':
 179     ****    Welcome to Gerrit Code Review    ****
 180     Hi <user>, you have successfully connected over SSH.
 181     Unfortunately, interactive shells are disabled.
 182     To clone a hosted Git repository, use: git clone ssh://<user>@git.opendaylight.org:29418/REPOSITORY_NAME.git
 183     Connection to git.opendaylight.org closed.
 184
 185 You can now proceed to either Pulling, Hacking, and Pushing the Code
 186 from the CLI or Pulling, Hacking, and Pushing the Code from Eclipse
 187 depending on your implementation.