--- /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
+Freenode.net
+
+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