diff options
Diffstat (limited to 'docs/07_How_To_Contribute/03_Working_with_Gerrit.md')
| -rw-r--r-- | docs/07_How_To_Contribute/03_Working_with_Gerrit.md | 153 |
1 files changed, 153 insertions, 0 deletions
diff --git a/docs/07_How_To_Contribute/03_Working_with_Gerrit.md b/docs/07_How_To_Contribute/03_Working_with_Gerrit.md new file mode 100644 index 0000000..ccd9133 --- /dev/null +++ b/docs/07_How_To_Contribute/03_Working_with_Gerrit.md @@ -0,0 +1,153 @@ +--- +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. |