---
This document presents some best practices to help you use Gerrit more
-effectively. The intent is to show how content can be submitted easily.
-Use the recommended practices to reduce your troubleshooting time and
-improve participation in the community.
+effectively. The intent is to show how content can be submitted easily. Use the
+recommended practices to reduce your troubleshooting time and improve
+participation in the community.
## Commit Messages
-Gerrit follows the Git commit message format. Ensure the headers are at
-the bottom and don't contain blank lines between one another. The
-following example shows the format and content expected in a commit
-message:
+Gerrit follows the Git commit message format. Ensure the headers are at the
+bottom and don't contain blank lines between one another. The following example
+shows the format and content expected in a commit message:
Brief (no more than 50 chars) one line description.
-Elaborate summary of the changes made referencing why (motivation), what
-was changed and how it was tested. Note also any changes to
-documentation made to remain consistent with the code changes, wrapping
-text at 72 chars/line.
+Elaborate summary of the changes made referencing why (motivation), what was
+changed and how it was tested. Note also any changes to documentation made to
+remain consistent with the code changes, wrapping text at 72 chars/line.
```sh
Bug-AGL: SPEC-<JIRA-ID>
Signed-off-by: Your Name your.email\@example.org
```
-The Gerrit server provides a precommit hook to autogenerate the
-Change-Id which is one time use.
+The Gerrit server provides a precommit hook to autogenerate the Change-Id which
+is one time use.
-**Recommended reading:** [How to Write a Git Commit Message](http://chris.beams.io/posts/git-commit/).
+**Recommended reading:** [How to Write a Git Commit
+Message](http://chris.beams.io/posts/git-commit/).
## Avoid Pushing Untested Work to a Gerrit Server
To avoid pushing untested work to Gerrit.
-Check your work at least three times before pushing your change to
-Gerrit. Be mindful of what information you are publishing.
+Check your work at least three times before pushing your change to Gerrit. Be
+mindful of what information you are publishing.
## Keeping Track of Changes
- Set Gerrit to send you emails:
- Gerrit will add you to the email distribution list for a change if a
- developer adds you as a reviewer, or if you comment on a specific
- Patch Set.
+ developer adds you as a reviewer, or if you comment on a specific Patch Set.
-- Opening a change in Gerrit's review interface is a quick way to
- follow that change.
+- Opening a change in Gerrit's review interface is a quick way to follow that
+ change.
-- Watch projects in the Gerrit projects section at ``Gerrit``, select
- at least *New Changes, New Patch Sets, All Comments* and *Submitted
- Changes*.
+- Watch projects in the Gerrit projects section at ``Gerrit``, select at least
+ *New Changes, New Patch Sets, All Comments* and *Submitted Changes*.
-Always track the projects you are working on; also see the
-feedback/comments [mailing list](https://lists.automotivelinux.org/g/agl-dev-community)
-to learn and help others ramp up.
+Always track the projects you are working on; also see the feedback/comments
+[mailing list](https://lists.automotivelinux.org/g/agl-dev-community) to learn
+and help others ramp up.
## Topic branches
Topic branches are temporary branches that you push to commit a set of
logically-grouped dependent commits:
-To push changes from ``REMOTE/master`` tree to Gerrit for being reviewed
-as a topic in **TopicName** use the following command as an example:
+To push changes from ``REMOTE/master`` tree to Gerrit for being reviewed as a
+topic in **TopicName** use the following command as an example:
```sh
$ git push REMOTE HEAD:refs/for/master/TopicName
```
-The topic will show up in the review ``UI`` and in the
-``Open Changes List``. Topic branches will disappear from the master
-tree when its content is merged.
+The topic will show up in the review ``UI`` and in the ``Open Changes List``.
+Topic branches will disappear from the master tree when its content is merged.
## Finding Available Topics
$ ssh -p 29418 <LFID>@gerrit.automotivelinux.org gerrit query \ status:open branch:master| grep topic: | sort -u
```
-- [gerrit.automotivelinux.org](https://gerrit.automotivelinux.org) is the current URL where the project is hosted.
-- *status* : Indicates the topic's current status: open , merged,
- abandoned, draft, merge conflict.
-- *project* : Refers to the current name of the project, in this case
- fabric.
+- [gerrit.automotivelinux.org](https://gerrit.automotivelinux.org) is the
+ current URL where the project is hosted.
+- *status* : Indicates the topic's current status: open , merged, abandoned,
+ draft, merge conflict.
+- *project* : Refers to the current name of the project, in this case fabric.
- *branch* : The topic is searched at this branch.
-- *topic* : The name of an specific topic, leave it blank to include them
- all.
+- *topic* : The name of an specific topic, leave it blank to include them all.
- *sort* : Sorts the found topics, in this case by update (-u).
## Downloading or Checking Out a Change
-In the review UI, on the top right corner, the **Download** link
-provides a list of commands and hyperlinks to checkout or download diffs
-or files.
+In the review UI, on the top right corner, the **Download** link provides a list
+of commands and hyperlinks to checkout or download diffs or files.
-We recommend the use of the *git review* plugin. The steps to install
-git review are beyond the scope of this document. Refer to the
-[git review documentation](https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers)
+We recommend the use of the *git review* plugin. The steps to install git review
+are beyond the scope of this document. Refer to the [git review
+documentation](https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers)
for the installation process.
-To check out a specific change using Git, the following command usually
-works:
+To check out a specific change using Git, the following command usually works:
```sh
$ git review -d CHANGEID
```
-If you don't have Git-review installed, the following commands will do
-the same thing:
+If you don't have Git-review installed, the following commands will do the same
+thing:
```sh
$ git fetch REMOTE refs/changes/NN/CHANGEIDNN/VERSION \ && git checkout FETCH_HEAD
```
-For example, for the 4th version of change 2464, NN is the first two
-digits (24):
+For example, for the 4th version of change 2464, NN is the first two digits
+(24):
```sh
$ git fetch REMOTE refs/changes/24/2464/4 \ && git checkout FETCH_HEAD
## Using Sandbox Branches
-You can create your own branches to develop features. The branches are
-pushed to the ``refs/heads/sandbox/USERNAME/BRANCHNAME`` location.
+You can create your own branches to develop features. The branches are pushed to
+the ``refs/heads/sandbox/USERNAME/BRANCHNAME`` location.
These commands ensure the branch is created in Gerrit's server.
## Updating the Version of a Change
-During the review process, you might be asked to update your change. It
-is possible to submit multiple versions of the same change. Each version
-of the change is called a patch set.
+During the review process, you might be asked to update your change. It is
+possible to submit multiple versions of the same change. Each version of the
+change is called a patch set.
-Always maintain the **Change-Id** that was assigned. For example, there
-is a list of commits, **c0...c7**, which were submitted as a topic
-branch:
+Always maintain the **Change-Id** that was assigned. For example, there is a
+list of commits, **c0...c7**, which were submitted as a topic branch:
```sh
$ git push REMOTE HEAD:refs/for/master/SOMETOPIC
```
-After you get reviewers' feedback, there are changes in **c3** and
-**c4** that must be fixed. If the fix requires rebasing, rebasing
-changes the commit Ids, see the [rebasing](http://git-scm.com/book/en/v2/Git-Branching-Rebasing) section for more information. However, you must keep the same Change-Id
-and push the changes again:
+After you get reviewers' feedback, there are changes in **c3** and **c4** that
+must be fixed. If the fix requires rebasing, rebasing changes the commit Ids,
+see the [rebasing](http://git-scm.com/book/en/v2/Git-Branching-Rebasing) section
+for more information. However, you must keep the same Change-Id and push the
+changes again:
```sh
$ git push REMOTE HEAD:refs/for/master/SOMETOPIC
```
-This new push creates a patches revision, your local history is then
-cleared. However you can still access the history of your changes in
-Gerrit on the ``review UI`` section, for each change.
+This new push creates a patches revision, your local history is then cleared.
+However you can still access the history of your changes in Gerrit on the
+``review UI`` section, for each change.
It is also permitted to add more commits when pushing new versions.
### Rebasing
-Rebasing is usually the last step before pushing changes to Gerrit; this
-allows you to make the necessary *Change-Ids*. The *Change-Ids* must be
-kept the same.
+Rebasing is usually the last step before pushing changes to Gerrit; this allows
+you to make the necessary *Change-Ids*. The *Change-Ids* must be kept the same.
- **squash:** mixes two or more commits into a single one.
- **reword:** changes the commit message.
Before pushing a rebase to your master, ensure that the history has a
consecutive order.
-For example, your ``REMOTE/master`` has the list of commits from **a0**
-to **a4**; Then, your changes **c0...c7** are on top of **a4**; thus:
+For example, your ``REMOTE/master`` has the list of commits from **a0** to
+**a4**; Then, your changes **c0...c7** are on top of **a4**; thus:
```sh
$ git log --oneline REMOTE/master..master
c7
```
-If ``REMOTE/master`` receives commits **a5**, **a6** and **a7**. Pull
-with a rebase as follows:
+If ``REMOTE/master`` receives commits **a5**, **a6** and **a7**. Pull with a
+rebase as follows:
```sh
$ git pull --rebase REMOTE master
## Getting Better Logs from Git
-Use these commands to change the configuration of Git in order to
-produce better logs:
+Use these commands to change the configuration of Git in order to produce better
+logs:
```sh
$ git config log.abbrevCommit true
$ git config log.abbrev 5
```
-The command above sets the abbreviation length to the last 5 characters
-of the hash.
+The command above sets the abbreviation length to the last 5 characters of the
+hash.
```sh
$ git config format.pretty oneline
```
-The command above avoids the insertion of an unnecessary line before the
-Author line.
+The command above avoids the insertion of an unnecessary line before the Author
+line.
Code Review / AGL / documentation.git / blobdiff