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