blob: 323b32a90847486cb257d2f93b72cba11d398d57 [file] [log] [blame]
David Shevitz6493b2f2017-08-03 14:53:29 -07001= Changes
2
3A change represents a single commit under review. Each change is identified
4by a <<change-id>>.
5
6Multiple git commits can share the same Change-Id, allowing you to update a
7change as you receive feedback through the code review process. In Gerrit,
8commits that share the same Change-Id are referred to as _patch sets_. When a
9change is approved, only the latest version of a commit is submitted to the
10repository.
11
12You can view a specific change using Gerrit's Review screen. This screen
13provides the following information for each change:
14
15* Current and previous patch sets
16* <<Change properties>>, such as owner, project, and target branch
Jakub Sokół13bac472020-09-17 16:07:50 +020017* Comments
David Shevitz6493b2f2017-08-03 14:53:29 -070018* Votes on link:config-labels.html[Review Labels]
19* The <<change-id>>
20
21[[change-properties]]
22== Change properties
23
24When you open a change in Gerrit, the Review screen displays a number of
25properties about that change.
26
27.Change Properties
28|===
29|Property|Description
30
31|Updated
32|The date on which the change was last updated.
33
34|Owner
35|The contributor who created the change.
36
Edwin Kempin60fcf2d2022-05-23 12:24:08 +020037|Uploader
38|The user that uploaded the current patch set (e.g. the user that executed the
39`git push` command, or the user that triggered the patch set creation through
40an action in the UI).
41
David Shevitz6493b2f2017-08-03 14:53:29 -070042|Reviewers
43|A list of one or more contributors responsible for reviewing the change.
44
45|CC
46|A list of one or more contributors who are kept informed about the change, but
47are not required to review it.
48
49|Project
50|The name of the Gerrit project.
51
52|Branch
53|The branch on which the change was made.
54
55|Topic
56|An optional topic.
57
58|Strategy
David Pursehouse3727dba2018-09-27 12:57:37 +090059|The <<submit-strategies,submit strategy>> for the change.
David Shevitz6493b2f2017-08-03 14:53:29 -070060
61|Code Review
62|Displays the Code Review status for the change.
63
64|===
65
66In addition, Gerrit displays the status of any additional labels, such as
67the Verified label, that have been configured for the server. See
68link:config-labels.html[Review Labels] for more information.
69
70[[change-message]]
71== Change Message
72
73Next to the list of change properties is the change message. This message
74contains user-supplied information regarding what the change does. To modify
75the change message, click the *Edit* link.
76
77By default, the change message contains the Change-Id. This ID contains a
78permanent link to a search for that Change-Id in Gerrit.
79
80[[related-changes]]
81== Related Changes
82
83In some cases, a change may be dependent on another change. These changes are
84listed next to the change message. These related changes are grouped together in
85several categories, including:
86
87* Relation Chain. These changes are related by parent-child relationships,
David Pursehouse2919b012018-09-27 12:59:12 +090088 regardless of <<topic,topic>>.
David Shevitz6493b2f2017-08-03 14:53:29 -070089* Merge Conflicts. These are changes in which there is a merge conflict with
90 the current change.
David Pursehouse2919b012018-09-27 12:59:12 +090091* Submitted Together. These are changes that share the same <<topic,topic>>.
David Shevitz6493b2f2017-08-03 14:53:29 -070092
93An arrow indicates the change you are currently viewing.
94
95[[topic]]
96== Topics
97
98Changes can be grouped by topics. Topics make it easier to find related changes
99by using the topic search operator. Changes with the same topic also appear in
100the *Relation Chain* section of the Review screen.
101
102Grouping changes by topics can be helpful when you have several changes that,
103when combined, implement a feature.
104
105Assigning a topic to a change can be done in the change screen or through a `git
106push` command.
107
Albert Cuiacef5c92021-02-26 19:42:27 +0000108For more information about using topics, see the user guide:
109link:cross-repository-changes.html[Submitting Changes Across Repositories by using Topics].
110
David Shevitz6493b2f2017-08-03 14:53:29 -0700111[[submit-strategies]]
112== Submit strategies
113
114Each project in Gerrit can employ a specific submit strategy. This strategy is
115listed in the change properties section of the Review screen.
116
117The following table lists the supported submit strategies.
118
119.Submit Strategies
120|===
121|Strategy|Description
122
123|Fast Forward Only
124|No merge commits are produced. All merges must be handled on the client, before
125submitting the change.
126
127To submit a change, the change must be a strict superset of the destination
128branch.
129
130|Merge If Necessary
131|The default submit strategy. If the change being submitted is a strict superset
132of the destination branch, then the branch is fast-forwarded to the change. If
133not, a merge commit is automatically created at submit time. This is identical
134to the `git merge --ff` command.
135
136|Always Merge
137|Always produce a merge commit, even if the change is a strict superset of the
138destination branch. This is identical to the `git merge --no-ff` command.
139It is often used when users of the project want to be able to read the history
140of submits by running the `git log --first-parent` command.
141
142|Cherry Pick
143|Always cherry pick the patch set, ignoring the parent lineage and instead
144creating a new commit on top of the current branch.
145
146When cherry picking a change, Gerrit automatically appends a short summary of
147the change's approvals and a link back to the change. The committer header is
148also set to the submitter, while the author header retains the original patch
149set author.
150
151NOTE: Gerrit ignores dependencies between changes when using this submit type
152unless `change.submitWholeTopic` is enabled and depending changes share the same
153topic. This means submitters must remember to submit changes in the right order
154when using this submit type.
155
156|Rebase if Necessary
157|If the change being submitted is a strict superset of the destination branch,
158the branch is fast-forwarded to the change. If not, the change is automatically
159rebased and the branch is fast-forwarded to the change.
160
161|Rebase Always
162|Similar to Rebase If Necessary, but creates a new patch set even if fast
163forward is possible. This strategy is also similar to Cherry Pick; however,
164Rebase Always does not ignore dependencies.
165
166|===
167
168Any project owner can use the Project screen to modify the method Gerrit uses
169to submit a change.
170
171[[change-id]]
172== Change-Id
173
174Gerrit uses a Change-Id to identify which patch sets belong to the same review.
175For example, you make a change to a project. A reviewer supplies some feedback,
Jonathan Nieder988abed2018-04-25 17:54:54 -0700176which you address in an amended commit. By assigning the same Change-Id to both
David Shevitz6493b2f2017-08-03 14:53:29 -0700177commits, Gerrit can attach those commits to the same change.
178
179Change-Ids are appended to the end of a commit message, and resemble the
180following:
181
182....
183commit 29a6bb1a059aef021ac39d342499191278518d1d
184Author: A. U. Thor <author@example.com>
185Date: Thu Aug 20 12:46:50 2009 -0700
186
187 Improve foo widget by attaching a bar.
188
189 We want a bar, because it improves the foo by providing more
190 wizbangery to the dowhatimeanery.
191
192 Bug: #42
193 Change-Id: Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b
194 Signed-off-by: A. U. Thor <author@example.com>
195 CC: R. E. Viewer <reviewer@example.com>
196....
197
198Gerrit requires that the Change-Id is in the footer (last paragraph) of a
199commit message. It can be combined with a Signed-off-by, CC, or other lines. For
200instance, the previous example has a Change-Id, along with a Signed-off-by and
201CC line.
202
203Notice that the Change-Id is similar to the commit id. To avoid confusing the
204two, a Change-Id typically begins with an `I`.
205
206While there are several ways you can add a Change-Id, the standard
207method uses git's link:cmd-hook-commit-msg.html[commit-msg hook]
208to automatically add the Change-Id to each new commit.
209
Peter Collingbourne8cab9332020-08-18 14:42:44 -0700210== The Link footer
211
212Gerrit also supports the Link footer as an alternative to the Change-Id
213footer. A Link footer looks like this:
214
215....
216 Link: https://gerrit-review.googlesource.com/id/Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b
217....
218
219The advantage of this style of footer is that it usually acts
220as a link directly to the change's review page, provided that
221the change has been uploaded to Gerrit. Projects such as the
222link:https://www.kernel.org/doc/html/latest/maintainer/configure-git.html#creating-commit-links-to-lore-kernel-org[Linux kernel]
223have a convention of adding links to commit messages using the
224Link footer.
225
226If multiple changes have been uploaded to Gerrit with the same
227change ID, for example if a change has been cherry-picked to multiple
228branches, the link will take the user to a list of changes.
229
230The base URL in the footer is required to match the server's base URL.
231If the URL does not match, the server will not recognize the footer
232as a change ID footer.
233
234The link:cmd-hook-commit-msg.html[commit-msg hook] can be configured
235to insert Link footers instead of Change-Id footers by setting the
236property `gerrit.reviewUrl` to the base URL of the Gerrit server.
237
David Shevitz6493b2f2017-08-03 14:53:29 -0700238GERRIT
239------
240Part of link:index.html[Gerrit Code Review]
241
242SEARCHBOX
243---------