2 title: Working with Gerrit
5 Follow these instructions to collaborate on AGL through the Gerrit review
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
12 Gerrit assigns the following roles to users:
14 - **Submitters**: May submit changes for consideration, review other code
15 changes, and make recommendations for acceptance or rejection by voting +1 or
17 - **Maintainers**: May approve or reject changes based upon feedback from
18 reviewers voting +2 or -2, respectively.
20 ## Getting deeper into Gerrit
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).
28 ## Working with a local clone of the repository
30 To work on something, whether a new feature or a bugfix:
32 1. Open the Gerrit [repo
33 page](https://gerrit.automotivelinux.org/gerrit/admin/repos/).
35 2. Select the repository you wish to work on.
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:
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/"
46 4. Setup `user` and `email` for git config
50 $ git config --global user.name "Your Full Name"
51 $ git config --global user.email "your@email.com"
54 **NOTE:** To only configure for a particular repository :
58 $ git config user.name "Your Full Name"
59 $ git config user.email "your@email.com"
62 5. Create a descriptively-named branch off of your cloned repository
65 $ git checkout -b issue-nname
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.
77 # for first time use only
80 If `.gitreview` is missing, add the following section to ``.git/config``, and
81 replace ``<LFID>`` with your LFID id.
85 url = ssh://<LFID>@gerrit.automotivelinux.org:29418/AGL/documentation.git
86 fetch = +refs/heads/*:refs/remotes/gerrit/*
89 Then submit your change with ``git review``.
96 When you update your patch, you can commit with ``git commit --amend``, and then
97 repeat the ``git review`` command.
99 ## Typical Review Workflow
104 $ cd documentation # Working Repository
105 $ git remote -v update # Updating wrt remote
106 $ git checkout -b mytopicbranch origin/octopus # Creating new branch
108 $ git add <file> # Track the changed files
109 $ git commit -s # Signed Commit Message
110 $ git review # Submit Changes to review
113 - Updating existing Gerrit Review
116 $ cd documentation # Working Repository
117 $ git review -d 25678 # Download review, 25678 is change number
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 octopus # Return to octopus branch
125 ## Reviewing Using Gerrit
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.
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.
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
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.
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.
152 The history tab in Gerrit will show you the in-line comments and the author of