212 lines
6.9 KiB
Plaintext
212 lines
6.9 KiB
Plaintext
= Changes
|
|
|
|
A change represents a single commit under review. Each change is identified
|
|
by a <<change-id>>.
|
|
|
|
Multiple git commits can share the same Change-Id, allowing you to update a
|
|
change as you receive feedback through the code review process. In Gerrit,
|
|
commits that share the same Change-Id are referred to as _patch sets_. When a
|
|
change is approved, only the latest version of a commit is submitted to the
|
|
repository.
|
|
|
|
You can view a specific change using Gerrit's Review screen. This screen
|
|
provides the following information for each change:
|
|
|
|
* Current and previous patch sets
|
|
* <<Change properties>>, such as owner, project, and target branch
|
|
* link:CONCEPT-comments.html[Comments]
|
|
* Votes on link:config-labels.html[Review Labels]
|
|
* The <<change-id>>
|
|
|
|
[[change-properties]]
|
|
== Change properties
|
|
|
|
When you open a change in Gerrit, the Review screen displays a number of
|
|
properties about that change.
|
|
|
|
.Change Properties
|
|
|===
|
|
|Property|Description
|
|
|
|
|Updated
|
|
|The date on which the change was last updated.
|
|
|
|
|Owner
|
|
|The contributor who created the change.
|
|
|
|
|Assignee
|
|
|The contributor responsible for the change. Often used when a change has
|
|
mulitple reviewers to identify the individual responsible for final approval.
|
|
|
|
|Reviewers
|
|
|A list of one or more contributors responsible for reviewing the change.
|
|
|
|
|CC
|
|
|A list of one or more contributors who are kept informed about the change, but
|
|
are not required to review it.
|
|
|
|
|Project
|
|
|The name of the Gerrit project.
|
|
|
|
|Branch
|
|
|The branch on which the change was made.
|
|
|
|
|Topic
|
|
|An optional topic.
|
|
|
|
|Strategy
|
|
|The <<submit-strategy>> for the change.
|
|
|
|
|Code Review
|
|
|Displays the Code Review status for the change.
|
|
|
|
|===
|
|
|
|
In addition, Gerrit displays the status of any additional labels, such as
|
|
the Verified label, that have been configured for the server. See
|
|
link:config-labels.html[Review Labels] for more information.
|
|
|
|
[[change-message]]
|
|
== Change Message
|
|
|
|
Next to the list of change properties is the change message. This message
|
|
contains user-supplied information regarding what the change does. To modify
|
|
the change message, click the *Edit* link.
|
|
|
|
By default, the change message contains the Change-Id. This ID contains a
|
|
permanent link to a search for that Change-Id in Gerrit.
|
|
|
|
[[related-changes]]
|
|
== Related Changes
|
|
|
|
In some cases, a change may be dependent on another change. These changes are
|
|
listed next to the change message. These related changes are grouped together in
|
|
several categories, including:
|
|
|
|
* Relation Chain. These changes are related by parent-child relationships,
|
|
regardless of <<topics>>.
|
|
* Merge Conflicts. These are changes in which there is a merge conflict with
|
|
the current change.
|
|
* Submitted Together. These are changes that share the same <<topics>>.
|
|
|
|
An arrow indicates the change you are currently viewing.
|
|
|
|
[[topic]]
|
|
== Topics
|
|
|
|
Changes can be grouped by topics. Topics make it easier to find related changes
|
|
by using the topic search operator. Changes with the same topic also appear in
|
|
the *Relation Chain* section of the Review screen.
|
|
|
|
Grouping changes by topics can be helpful when you have several changes that,
|
|
when combined, implement a feature.
|
|
|
|
Assigning a topic to a change can be done in the change screen or through a `git
|
|
push` command.
|
|
|
|
[[submit-strategies]]
|
|
== Submit strategies
|
|
|
|
Each project in Gerrit can employ a specific submit strategy. This strategy is
|
|
listed in the change properties section of the Review screen.
|
|
|
|
The following table lists the supported submit strategies.
|
|
|
|
.Submit Strategies
|
|
|===
|
|
|Strategy|Description
|
|
|
|
|Fast Forward Only
|
|
|No merge commits are produced. All merges must be handled on the client, before
|
|
submitting the change.
|
|
|
|
To submit a change, the change must be a strict superset of the destination
|
|
branch.
|
|
|
|
|Merge If Necessary
|
|
|The default submit strategy. If the change being submitted is a strict superset
|
|
of the destination branch, then the branch is fast-forwarded to the change. If
|
|
not, a merge commit is automatically created at submit time. This is identical
|
|
to the `git merge --ff` command.
|
|
|
|
|Always Merge
|
|
|Always produce a merge commit, even if the change is a strict superset of the
|
|
destination branch. This is identical to the `git merge --no-ff` command.
|
|
It is often used when users of the project want to be able to read the history
|
|
of submits by running the `git log --first-parent` command.
|
|
|
|
|Cherry Pick
|
|
|Always cherry pick the patch set, ignoring the parent lineage and instead
|
|
creating a new commit on top of the current branch.
|
|
|
|
When cherry picking a change, Gerrit automatically appends a short summary of
|
|
the change's approvals and a link back to the change. The committer header is
|
|
also set to the submitter, while the author header retains the original patch
|
|
set author.
|
|
|
|
NOTE: Gerrit ignores dependencies between changes when using this submit type
|
|
unless `change.submitWholeTopic` is enabled and depending changes share the same
|
|
topic. This means submitters must remember to submit changes in the right order
|
|
when using this submit type.
|
|
|
|
|Rebase if Necessary
|
|
|If the change being submitted is a strict superset of the destination branch,
|
|
the branch is fast-forwarded to the change. If not, the change is automatically
|
|
rebased and the branch is fast-forwarded to the change.
|
|
|
|
|Rebase Always
|
|
|Similar to Rebase If Necessary, but creates a new patch set even if fast
|
|
forward is possible. This strategy is also similar to Cherry Pick; however,
|
|
Rebase Always does not ignore dependencies.
|
|
|
|
|===
|
|
|
|
Any project owner can use the Project screen to modify the method Gerrit uses
|
|
to submit a change.
|
|
|
|
[[change-id]]
|
|
== Change-Id
|
|
|
|
Gerrit uses a Change-Id to identify which patch sets belong to the same review.
|
|
For example, you make a change to a project. A reviewer supplies some feedback,
|
|
which you address in an amended commit. By assigning the same Change-Id to both
|
|
commits, Gerrit can attach those commits to the same change.
|
|
|
|
Change-Ids are appended to the end of a commit message, and resemble the
|
|
following:
|
|
|
|
....
|
|
commit 29a6bb1a059aef021ac39d342499191278518d1d
|
|
Author: A. U. Thor <author@example.com>
|
|
Date: Thu Aug 20 12:46:50 2009 -0700
|
|
|
|
Improve foo widget by attaching a bar.
|
|
|
|
We want a bar, because it improves the foo by providing more
|
|
wizbangery to the dowhatimeanery.
|
|
|
|
Bug: #42
|
|
Change-Id: Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b
|
|
Signed-off-by: A. U. Thor <author@example.com>
|
|
CC: R. E. Viewer <reviewer@example.com>
|
|
....
|
|
|
|
Gerrit requires that the Change-Id is in the footer (last paragraph) of a
|
|
commit message. It can be combined with a Signed-off-by, CC, or other lines. For
|
|
instance, the previous example has a Change-Id, along with a Signed-off-by and
|
|
CC line.
|
|
|
|
Notice that the Change-Id is similar to the commit id. To avoid confusing the
|
|
two, a Change-Id typically begins with an `I`.
|
|
|
|
While there are several ways you can add a Change-Id, the standard
|
|
method uses git's link:cmd-hook-commit-msg.html[commit-msg hook]
|
|
to automatically add the Change-Id to each new commit.
|
|
|
|
GERRIT
|
|
------
|
|
Part of link:index.html[Gerrit Code Review]
|
|
|
|
SEARCHBOX
|
|
---------
|