docs/5_How_To_Contribute/3_Working_with_Gerrit.md

   1 ---
   2 title: Working with Gerrit
   3 ---
   4
   5 Follow these instructions to collaborate on AGL through the Gerrit review system.
   6
   7 Please be sure that you are subscribed to the [mailing
   8 list](https://lists.automotivelinux.org/g/agl-dev-community) and of
   9 course, you can reach out on IRC at the #automotive channel on
  10 Freenode.net
  11
  12 Gerrit assigns the following roles to users:
  13
  14 -  **Submitters**: May submit changes for consideration, review other
  15    code changes, and make recommendations for acceptance or rejection by
  16    voting +1 or -1, respectively.
  17 -  **Maintainers**: May approve or reject changes based upon feedback
  18    from reviewers voting +2 or -2, respectively.
  19
  20 ## Getting deeper into Gerrit
  21
  22 A comprehensive walk-through of Gerrit is beyond the scope of this
  23 document. There are plenty of resources available on the Internet. A good
  24 summary can be found
  25 [here](https://www.mediawiki.org/wiki/Gerrit/Tutorial) and
  26 [Basic Gerrit Walkthrough for GitHub Users](https://gerrit-review.googlesource.com/Documentation/intro-gerrit-walkthrough-github.html).
  27
  28 ## Working with a local clone of the repository
  29
  30 To work on something, whether a new feature or a bugfix:
  31
  32 1. Open the Gerrit [repo page](https://gerrit.automotivelinux.org/gerrit/admin/repos/).
  33
  34 2. Select the repository you wish to work on.
  35
  36 3. Open a terminal window and clone the project locally using the
  37    ``Clone with git hook`` URL. Be sure that ``ssh`` is also selected,
  38    as this will make authentication much simpler. For example, for `documentation` repository:
  39
  40     ```sh
  41     $ git clone "ssh://<LFID>@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P
  42     29418 <LFID>@gerrit.automotivelinux.org:hooks/commit-msg "documentation/.git/hooks/"
  43     ```
  44
  45 4. Setup `user` and `email` for git config
  46
  47     ```sh
  48      $ cd documentation
  49      $ git.config --global user.name "Your Full Name"
  50      $ git config --global user.email "your@email.com"
  51     ```
  52
  53       **NOTE:** To only configure for a particular repository :
  54
  55     ```sh
  56      $ cd documentation
  57      $ git.config user.name "Your Full Name"
  58      $ git config user.email "your@email.com"
  59     ```
  60
  61 5. Create a descriptively-named branch off of your cloned repository
  62
  63     ```sh
  64      $ git checkout -b issue-nname
  65     ```
  66
  67 ## Using git review
  68
  69 There's a **very** useful tool for working with Gerrit called [git-review](https://www.mediawiki.org/wiki/Gerrit/git-review). This command-line tool can automate most of the ensuing sections for you. Ofcourse, reading the information below is also highly recommended so that you understand what's going on behind the scenes.
  70
  71 ```sh
  72 # for first time use only
  73 $ git review -s
  74 ```
  75 If `.gitreview` is missing, add the following section to ``.git/config``, and replace ``<LFID>``
  76 with your LFID id.
  77
  78 ```sh
  79 [remote "gerrit"]
  80    url = ssh://<LFID>@gerrit.automotivelinux.org:29418/AGL/documentation.git
  81    fetch = +refs/heads/*:refs/remotes/gerrit/*
  82 ```
  83
  84 Then submit your change with ``git review``.
  85
  86 ```sh
  87 $ cd documentation
  88 $ git review
  89 ```
  90
  91 When you update your patch, you can commit with ``git commit --amend``,
  92 and then repeat the ``git review`` command.
  93
  94 ## Typical Review Workflow
  95
  96    - New Fresh Change
  97
  98       ```sh
  99       $ cd documentation                              # Working Repository
 100       $ git remote -v update                          # Updating wrt remote
 101       $ git checkout -b mytopicbranch origin/master   # Creating new branch
 102       ### CODE the CHANGES
 103       $ git add  <file>                               # Track the changed files
 104       $ git commit -s                                 # Signed Commit Message
 105       $ git review                                    # Submit Changes to review
 106       ```
 107
 108    - Updating existing Gerrit Review
 109
 110       ```sh
 111       $ cd documentation                              # Working Repository
 112       $ git review -d 25678                           # Download review, 25678 is change number
 113       ### CODE the CHANGES
 114       $ git add  <file>                               # Track the changed files
 115       $ git commit -s                                 # Signed Commit Message
 116       $ git review                                    # Submit Changes to review
 117       $ git checkout master                           # Return to master branch
 118       ```
 119
 120 ## Reviewing Using Gerrit
 121
 122 -  **Add**: This button allows the change submitter to manually add
 123    names of people who should review a change; start typing a name and
 124    the system will auto-complete based on the list of people registered
 125    and with access to the system. They will be notified by email that
 126    you are requesting their input.
 127
 128 -  **Abandon**: This button is available to the submitter only; it
 129    allows a committer to abandon a change and remove it from the merge
 130    queue.
 131
 132 -  **Change-ID**: This ID is generated by Gerrit (or system). It becomes
 133    useful when the review process determines that your commit(s) have to
 134    be amended. You may submit a new version; and if the same Change-ID
 135    header (and value) are present, Gerrit will remember it and present
 136    it as another version of the same change.
 137
 138 -  **Status**: Currently, the example change is in review status, as
 139    indicated by “Needs Verified” in the upper-left corner. The list of
 140    Reviewers will all emit their opinion, voting +1 if they agree to the
 141    merge, -1 if they disagree. Gerrit users with a Maintainer role can
 142    agree to the merge or refuse it by voting +2 or -2 respectively.
 143
 144 Notifications are sent to the email address in your commit message's
 145 Signed-off-by line. Visit your [Gerrit dashboard](https://gerrit.automotivelinux.org/gerrit/dashboard/self),
 146 to check the progress of your requests.
 147
 148 The history tab in Gerrit will show you the in-line comments and the author of the review.