docs/developer-guide/pulling-and-pushing-the-code-from-the-cli.rst

   1 Pulling and Pushing the Code from the CLI
   2 =========================================
   3
   4 OpenDayligh is a collection of projects, each with their own code
   5 repository. This section provides a general guide for to pulling,
   6 hacking, and pushing the code for each project. For project specific
   7 detail, refer to the project’s section in this guide.
   8
   9 Code reviews are enabled through Gerrit. For setting up Gerrit see the
  10 section on Getting started with Git and Gerrit.
  11
  12 .. note::
  13
  14     You will need to perform the Gerrit Setup before you can access git
  15     via ssh as described below.
  16
  17 Pulling code via Git CLI
  18 ------------------------
  19
  20 Pull the code by cloning the project’s repository.
  21
  22 ::
  23
  24      git clone ssh://<username>@git.opendaylight.org:29418/<project_repo_name>.git
  25
  26 where <username> is your OpenDaylight username, and
  27 <project\_repo\_name> is the name of the repository for project you are
  28 trying to pull. Here is the current list of project repository names:
  29
  30 aaa, affinity, bgpcep, controller, defense4all, dlux, docs,
  31 groupbasedpolicy, integration, l2switch, lispflowmapping, odlparent,
  32 opendove, openflowjava, openflowplugin, opflex, ovsdb, packetcable,
  33 reservation, sdninterfaceapp, sfc, snbi, snmp4sdn, toolkit, ttp, vtn,
  34 yangtools.
  35
  36 For an anonymous git clone, you can use:
  37
  38 ::
  39
  40      git clone https://git.opendaylight.org/gerrit/p/<project_repo_name>.git
  41
  42 Setting up Gerrit Change-id Commit Message Hook
  43 -----------------------------------------------
  44
  45 -  This command inserts a unique Change-Id tag in the footer of a commit
  46    message. This step is optional but highly recommended for tracking
  47    changes.
  48
  49 ::
  50
  51      cd <project_repo_name>
  52      scp -p -P 29418 <username>@git.opendaylight.org:hooks/commit-msg .git/hooks/
  53      chmod 755 .git/hooks/commit-msg
  54
  55 -  Install and setup Git-review. Git-review is a great tool to simplify
  56    the hassle of using several git commands to submit a patch for
  57    review. Refer to `How to install and push codes with
  58    git-review <http://www.mediawiki.org/wiki/Gerrit/git-review#Installation%7Chere>`__
  59    for instructions. After initializing git-review, both commit-msg hook
  60    and a remote repo named gerrit will be created and a patch can be
  61    submitted to Gerrit with a single "git review" command.
  62
  63 -  Now you can start making your code changes.
  64
  65 Building the code
  66 -----------------
  67
  68 While you are in the <project\_repo\_name> directory, run
  69
  70 ::
  71
  72      mvn clean install
  73
  74 To run without unitests you can skip building those tests running the
  75 following:
  76
  77 ::
  78
  79      mvn clean install -DskipTests
  80      /* instead of "mvn clean install" */
  81
  82 Runing OpenDaylight from local build
  83 ------------------------------------
  84
  85 Change to the karaf distribution sub-directory, and run
  86
  87 ::
  88
  89      ./target/assembly/bin/karaf
  90
  91 At this point the OpenDaylight controller is running. You can now open a
  92 web browser and point your browser at http://localhost:8080/
  93
  94 .. figure:: ./images/800p_OpenDaylight_Login.jpg
  95    :alt: OpenDaylight Main Page
  96
  97    OpenDaylight Main Page
  98
  99 Commit the code using Git CLI
 100 -----------------------------
 101
 102 .. note::
 103
 104     To be accepted, all code mustcome with a `developer certificate of
 105     origin <http://elinux.org/Developer_Certificate_Of_Origin>`__ as
 106     expressed by having a Signed-off-by. This means that you are
 107     asserting that you have made the change and you understand that the
 108     work was done as part of an open-source license.
 109
 110 ::
 111
 112     Developer's Certificate of Origin 1.1
 113
 114             By making a contribution to this project, I certify that:
 115
 116             (a) The contribution was created in whole or in part by me and I
 117                 have the right to submit it under the open source license
 118                 indicated in the file; or
 119
 120             (b) The contribution is based upon previous work that, to the best
 121                 of my knowledge, is covered under an appropriate open source
 122                 license and I have the right under that license to submit that
 123                 work with modifications, whether created in whole or in part
 124                 by me, under the same open source license (unless I am
 125                 permitted to submit under a different license), as indicated
 126                 in the file; or
 127
 128             (c) The contribution was provided directly to me by some other
 129                 person who certified (a), (b) or (c) and I have not modified
 130                 it.
 131
 132             (d) I understand and agree that this project and the contribution
 133                 are public and that a record of the contribution (including all
 134                 personal information I submit with it, including my sign-off) is
 135                 maintained indefinitely and may be redistributed consistent with
 136                 this project or the open source license(s) involved.
 137
 138 **Mechanically you do it this way**:
 139
 140 ::
 141
 142     git commit --signoff
 143
 144 You will be prompted for a commit message. If you are fixing a buzilla
 145 bug you can add the associated bug number to your commit message and it
 146 will get linked from Gerrit:
 147
 148 **For Example:.**
 149
 150 ::
 151
 152     Fix for bug 2.
 153
 154     Signed-off-by: Ed Warnicke <eaw@cisco.com>
 155     # Please enter the commit message for your changes. Lines starting
 156     # with '#' will be ignored, and an empty message aborts the commit.
 157     # On branch develop
 158     # Changes to be committed:
 159     #   (use "git reset HEAD <file>..." to unstage)
 160     #
 161     #       modified:   README
 162     #
 163
 164 Pulling the Code changes via Git CLI
 165 ------------------------------------
 166
 167 Pull the latest changes from the remote repository
 168
 169 ::
 170
 171     git remote update
 172     git rebase origin/<project_main_branch_name>
 173
 174 where <project\_main\_branch\_name> is the the branch you want to commit
 175 to. For most projects this is master branch. For some projects such as
 176 lispflowmapping, a different branch name (develop in the case of
 177 lispflowmapping) should be used.
 178
 179 Pushing the Code via Git CLI
 180 ----------------------------
 181
 182 Use git review to push your changes back to the remote repository using:
 183
 184 ::
 185
 186      git review
 187
 188 You can set a topic for your patch by:
 189
 190 ::
 191
 192      git review -t <topic>
 193
 194 You will get a message pointing you to your gerrit request like:
 195
 196 ::
 197
 198     ==========================
 199     remote: Resolving deltas: 100% (2/2) +
 200     remote: Processing changes: new: 1, refs: 1, done    +
 201     remote: +
 202     remote: New Changes: +
 203     remote:   http://git.opendaylight.org/gerrit/64 +
 204     remote: +
 205     ==========================
 206
 207 The Jenkins Controller User will verify your code and post the result on
 208 the your gerrit request.
 209
 210 Viewing your Changes in Gerrit
 211 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 212
 213 Follow the link you got above to see your commit in Gerrit:
 214
 215 .. figure:: ./images/gerrit_code_review.jpg
 216    :alt: Gerritt Code Review Sample
 217
 218    Gerritt Code Review Sample
 219
 220 Note that the Jenkins Controller User has verified your code and at the
 221 bottom is a link to the Jenkins build.
 222
 223 Once your code has been reviewed and submitted by a committer it will be
 224 merged into the authoritative repo, which would look like this:
 225
 226 .. figure:: ./images/gerrit_merged.jpg
 227    :alt: Gerritt Code Merge Sample
 228
 229    Gerritt Code Merge Sample
 230
 231 Troubleshooting
 232 ~~~~~~~~~~~~~~~
 233
 234 1. **What to do if your Firewall blocks port 29418**
 235
 236 There have been reports that many corporate firewalls block port 29418.
 237 If that’s the case, please follow the `Setting up HTTP in
 238 Gerrit <https://wiki.opendaylight.org/view/OpenDaylight_Controller:Setting_up_HTTP_in_Gerrit>`__
 239 instructions and use git URL:
 240
 241 ::
 242
 243     git clone https://<your_username>@git.opendaylight.org/gerrit/p/<project_repo_name>.git
 244
 245 You will be prompted for the password you generated in `Setting up HTTP
 246 in
 247 Gerrit <https://wiki.opendaylight.org/view/OpenDaylight_Controller:Setting_up_HTTP_in_Gerrit>`__.
 248
 249 All other instructions on this page remain unchanged.
 250
 251 To download pre-built images with ODP bootstraps see the following
 252 Github project:
 253
 254 `Pre-Built OpenDaylight VM
 255 Images <https://github.com/nerdalert/OpenDaylight-Lab>`__
 256