2 title: Gerrit Recommended Practices
5 This document presents some best practices to help you use Gerrit more
6 effectively. The intent is to show how content can be submitted easily. Use the
7 recommended practices to reduce your troubleshooting time and improve
8 participation in the community.
12 Gerrit follows the Git commit message format. Ensure the headers are at the
13 bottom and don't contain blank lines between one another. The following example
14 shows the format and content expected in a commit message:
16 Brief (no more than 50 chars) one line description.
18 Elaborate summary of the changes made referencing why (motivation), what was
19 changed and how it was tested. Note also any changes to documentation made to
20 remain consistent with the code changes, wrapping text at 72 chars/line.
23 Bug-AGL: SPEC-<JIRA-ID>
25 Change-Id: LONGHEXHASH
26 Signed-off-by: Your Name your.email\@example.org
29 The Gerrit server provides a precommit hook to autogenerate the Change-Id which
32 **Recommended reading:** [How to Write a Git Commit
33 Message](http://chris.beams.io/posts/git-commit/).
35 ## Avoid Pushing Untested Work to a Gerrit Server
37 To avoid pushing untested work to Gerrit.
39 Check your work at least three times before pushing your change to Gerrit. Be
40 mindful of what information you are publishing.
42 ## Keeping Track of Changes
44 - Set Gerrit to send you emails:
46 - Gerrit will add you to the email distribution list for a change if a
47 developer adds you as a reviewer, or if you comment on a specific Patch Set.
49 - Opening a change in Gerrit's review interface is a quick way to follow that
52 - Watch projects in the Gerrit projects section at ``Gerrit``, select at least
53 *New Changes, New Patch Sets, All Comments* and *Submitted Changes*.
55 Always track the projects you are working on; also see the feedback/comments
56 [mailing list](https://lists.automotivelinux.org/g/agl-dev-community) to learn
57 and help others ramp up.
61 Topic branches are temporary branches that you push to commit a set of
62 logically-grouped dependent commits:
64 To push changes from ``REMOTE/master`` tree to Gerrit for being reviewed as a
65 topic in **TopicName** use the following command as an example:
68 $ git push REMOTE HEAD:refs/for/master/TopicName
71 The topic will show up in the review ``UI`` and in the ``Open Changes List``.
72 Topic branches will disappear from the master tree when its content is merged.
74 ## Finding Available Topics
77 $ ssh -p 29418 <LFID>@gerrit.automotivelinux.org gerrit query \ status:open branch:master| grep topic: | sort -u
80 - [gerrit.automotivelinux.org](https://gerrit.automotivelinux.org) is the
81 current URL where the project is hosted.
82 - *status* : Indicates the topic's current status: open , merged, abandoned,
83 draft, merge conflict.
84 - *project* : Refers to the current name of the project, in this case fabric.
85 - *branch* : The topic is searched at this branch.
86 - *topic* : The name of an specific topic, leave it blank to include them all.
87 - *sort* : Sorts the found topics, in this case by update (-u).
89 ## Downloading or Checking Out a Change
91 In the review UI, on the top right corner, the **Download** link provides a list
92 of commands and hyperlinks to checkout or download diffs or files.
94 We recommend the use of the *git review* plugin. The steps to install git review
95 are beyond the scope of this document. Refer to the [git review
96 documentation](https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers)
97 for the installation process.
99 To check out a specific change using Git, the following command usually works:
102 $ git review -d CHANGEID
105 If you don't have Git-review installed, the following commands will do the same
109 $ git fetch REMOTE refs/changes/NN/CHANGEIDNN/VERSION \ && git checkout FETCH_HEAD
112 For example, for the 4th version of change 2464, NN is the first two digits
116 $ git fetch REMOTE refs/changes/24/2464/4 \ && git checkout FETCH_HEAD
119 ## Using Sandbox Branches
121 You can create your own branches to develop features. The branches are pushed to
122 the ``refs/heads/sandbox/USERNAME/BRANCHNAME`` location.
124 These commands ensure the branch is created in Gerrit's server.
127 $ git checkout -b sandbox/USERNAME/BRANCHNAME
128 $ git push --set-upstream REMOTE HEAD:refs/heads/sandbox/USERNAME/BRANCHNAME
131 Usually, the process to create content is:
134 - break the information into small commits,
139 The next command pushes forcibly without review:
142 $ git push REMOTE sandbox/USERNAME/BRANCHNAME
145 You can also push forcibly with review:
148 $ git push REMOTE HEAD:ref/for/sandbox/USERNAME/BRANCHNAME
151 ## Updating the Version of a Change
153 During the review process, you might be asked to update your change. It is
154 possible to submit multiple versions of the same change. Each version of the
155 change is called a patch set.
157 Always maintain the **Change-Id** that was assigned. For example, there is a
158 list of commits, **c0...c7**, which were submitted as a topic branch:
162 $ git log REMOTE/master..master
168 $ git push REMOTE HEAD:refs/for/master/SOMETOPIC
171 After you get reviewers' feedback, there are changes in **c3** and **c4** that
172 must be fixed. If the fix requires rebasing, rebasing changes the commit Ids,
173 see the [rebasing](http://git-scm.com/book/en/v2/Git-Branching-Rebasing) section
174 for more information. However, you must keep the same Change-Id and push the
178 $ git push REMOTE HEAD:refs/for/master/SOMETOPIC
181 This new push creates a patches revision, your local history is then cleared.
182 However you can still access the history of your changes in Gerrit on the
183 ``review UI`` section, for each change.
185 It is also permitted to add more commits when pushing new versions.
189 Rebasing is usually the last step before pushing changes to Gerrit; this allows
190 you to make the necessary *Change-Ids*. The *Change-Ids* must be kept the same.
192 - **squash:** mixes two or more commits into a single one.
193 - **reword:** changes the commit message.
194 - **edit:** changes the commit content.
195 - **reorder:** allows you to interchange the order of the commits.
196 - **rebase:** stacks the commits on top of the master.
198 ## Rebasing During a Pull
200 Before pushing a rebase to your master, ensure that the history has a
203 For example, your ``REMOTE/master`` has the list of commits from **a0** to
204 **a4**; Then, your changes **c0...c7** are on top of **a4**; thus:
207 $ git log --oneline REMOTE/master..master
220 If ``REMOTE/master`` receives commits **a5**, **a6** and **a7**. Pull with a
224 $ git pull --rebase REMOTE master
227 This pulls **a5-a7** and re-apply **c0-c7** on top of them:
230 $ git log --oneline REMOTE/master..master
240 ## Getting Better Logs from Git
242 Use these commands to change the configuration of Git in order to produce better
246 $ git config log.abbrevCommit true
249 The command above sets the log to abbreviate the commits' hash.
252 $ git config log.abbrev 5
255 The command above sets the abbreviation length to the last 5 characters of the
259 $ git config format.pretty oneline
262 The command above avoids the insertion of an unnecessary line before the Author