--- /dev/null
+---
+title: Working with Gerrit
+---
+
+Follow these instructions to collaborate on AGL through the Gerrit review
+system.
+
+Please be sure that you are subscribed to the [mailing
+list](https://lists.automotivelinux.org/g/agl-dev-community) and of course, you
+can reach out on IRC at the #automotive channel on irc.libera.chat
+
+Gerrit assigns the following roles to users:
+
+- **Submitters**: May submit changes for consideration, review other code
+ changes, and make recommendations for acceptance or rejection by voting +1 or
+ -1, respectively.
+- **Maintainers**: May approve or reject changes based upon feedback from
+ reviewers voting +2 or -2, respectively.
+
+## Getting deeper into Gerrit
+
+A comprehensive walk-through of Gerrit is beyond the scope of this document.
+There are plenty of resources available on the Internet. A good summary can be
+found [here](https://www.mediawiki.org/wiki/Gerrit/Tutorial) and [Basic Gerrit
+Walkthrough for GitHub
+Users](https://gerrit-review.googlesource.com/Documentation/intro-gerrit-walkthrough-github.html).
+
+## Working with a local clone of the repository
+
+To work on something, whether a new feature or a bugfix:
+
+1. Open the Gerrit [repo
+ page](https://gerrit.automotivelinux.org/gerrit/admin/repos/).
+
+2. Select the repository you wish to work on.
+
+3. Open a terminal window and clone the project locally using the ``Clone with
+ git hook`` URL. Be sure that ``ssh`` is also selected, as this will make
+ authentication much simpler. For example, for `documentation` repository:
+
+ ```sh
+ $ git clone "ssh://<LFID>@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P
+ 29418 <LFID>@gerrit.automotivelinux.org:hooks/commit-msg "documentation/.git/hooks/"
+ ```
+
+4. Setup `user` and `email` for git config
+
+ ```sh
+ $ cd documentation
+ $ git.config --global user.name "Your Full Name"
+ $ git config --global user.email "your@email.com"
+ ```
+
+ **NOTE:** To only configure for a particular repository :
+
+ ```sh
+ $ cd documentation
+ $ git.config user.name "Your Full Name"
+ $ git config user.email "your@email.com"
+ ```
+
+5. Create a descriptively-named branch off of your cloned repository
+
+ ```sh
+ $ git checkout -b issue-nname
+ ```
+
+## Using git review
+
+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.
+
+```sh
+# for first time use only
+$ git review -s
+```
+If `.gitreview` is missing, add the following section to ``.git/config``, and
+replace ``<LFID>`` with your LFID id.
+
+```sh
+[remote "gerrit"]
+ url = ssh://<LFID>@gerrit.automotivelinux.org:29418/AGL/documentation.git
+ fetch = +refs/heads/*:refs/remotes/gerrit/*
+```
+
+Then submit your change with ``git review``.
+
+```sh
+$ cd documentation
+$ git review
+```
+
+When you update your patch, you can commit with ``git commit --amend``, and then
+repeat the ``git review`` command.
+
+## Typical Review Workflow
+
+ - New Fresh Change
+
+ ```sh
+ $ cd documentation # Working Repository
+ $ git remote -v update # Updating wrt remote
+ $ git checkout -b mytopicbranch origin/master # Creating new branch
+ ### CODE the CHANGES
+ $ git add <file> # Track the changed files
+ $ git commit -s # Signed Commit Message
+ $ git review # Submit Changes to review
+ ```
+
+ - Updating existing Gerrit Review
+
+ ```sh
+ $ cd documentation # Working Repository
+ $ git review -d 25678 # Download review, 25678 is change number
+ ### CODE the CHANGES
+ $ git add <file> # Track the changed files
+ $ git commit -s # Signed Commit Message
+ $ git review # Submit Changes to review
+ $ git checkout master # Return to master branch
+ ```
+
+## Reviewing Using Gerrit
+
+- **Add**: This button allows the change submitter to manually add names of
+ people who should review a change; start typing a name and the system will
+ auto-complete based on the list of people registered and with access to the
+ system. They will be notified by email that you are requesting their input.
+
+- **Abandon**: This button is available to the submitter only; it allows a
+ committer to abandon a change and remove it from the merge queue.
+
+- **Change-ID**: This ID is generated by Gerrit (or system). It becomes useful
+ when the review process determines that your commit(s) have to be amended.
+ You may submit a new version; and if the same Change-ID header (and value)
+ are present, Gerrit will remember it and present it as another version of the
+ same change.
+
+- **Status**: Currently, the example change is in review status, as indicated
+ by “Needs Verified” in the upper-left corner. The list of Reviewers will all
+ emit their opinion, voting +1 if they agree to the merge, -1 if they
+ disagree. Gerrit users with a Maintainer role can agree to the merge or
+ refuse it by voting +2 or -2 respectively.
+
+Notifications are sent to the email address in your commit message's
+Signed-off-by line. Visit your [Gerrit
+dashboard](https://gerrit.automotivelinux.org/gerrit/dashboard/self), to check
+the progress of your requests.
+
+The history tab in Gerrit will show you the in-line comments and the author of
+the review.
Code Review / AGL / documentation.git / blobdiff