Documentation/concept-changes.txt

= 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-strategies,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 <<topic,topic>>.
* 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 <<topic,topic>>.

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