[AGL/documentation.git] / docs / 5_How_To_Contribute / 6_Gerrit_Recommended_Practices.md

---
title: Gerrit Recommended Practices
---

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.

## 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:

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.

```sh
Bug-AGL: SPEC-<JIRA-ID>

Change-Id: LONGHEXHASH
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.

**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.

## 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.

-  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*.

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:

```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.

## Finding Available Topics

```sh
$ 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.
-  *branch* : The topic is searched at this branch.
-  *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.

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:

```sh
$ git review -d CHANGEID
```

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):

```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.

These commands ensure the branch is created in Gerrit's server.

```sh
$ git checkout -b sandbox/USERNAME/BRANCHNAME
$ git push --set-upstream REMOTE HEAD:refs/heads/sandbox/USERNAME/BRANCHNAME
```

Usually, the process to create content is:

-  develop the code,
-  break the information into small commits,
-  submit changes,
-  apply feedback,
-  rebase.

The next command pushes forcibly without review:

```sh
$ git push REMOTE sandbox/USERNAME/BRANCHNAME
```

You can also push forcibly with review:

```sh
$ git push REMOTE HEAD:ref/for/sandbox/USERNAME/BRANCHNAME
```

## 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.

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 log REMOTE/master..master

  c0
  ...
  c7

$ 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:

```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.

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.

-  **squash:** mixes two or more commits into a single one.
-  **reword:** changes the commit message.
-  **edit:** changes the commit content.
-  **reorder:** allows you to interchange the order of the commits.
-  **rebase:** stacks the commits on top of the master.

## Rebasing During a Pull

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:

```sh
$ git log --oneline REMOTE/master..master

  a0
  a1
  a2
  a3
  a4
  c0
  c1
  ...
  c7
```

If ``REMOTE/master`` receives commits **a5**, **a6** and **a7**. Pull
with a rebase as follows:

```sh
$ git pull --rebase REMOTE master
```

This pulls **a5-a7** and re-apply **c0-c7** on top of them:

```sh
$ git log --oneline REMOTE/master..master
a0
...
a7
c0
c1
...
c7
```

## Getting Better Logs from Git

Use these commands to change the configuration of Git in order to
produce better logs:

```sh
$ git config log.abbrevCommit true
```

The command above sets the log to abbreviate the commits' hash.

```sh
$ git config log.abbrev 5
```

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.