opendev/gerrit
Code Issues Proposed changes
97894c1588
gerrit/Documentation/concept-changes.txt
David Pursehouse b6fa44f8b5 Merge branch 'stable-2.15' 
* stable-2.15:
  AsyncReceiveCommits#onPreReceive: Early exit when commands already processed
  Replace download links for releases index page
  concept-changes: Fix 'invalid reference: topic' warning
  concept-changes: Fix 'invalid reference: submit-strategy' warning
  Set version to 2.14.14
  Update jruby to 9.1.17 and asciidoctorj to v1.5.7
  Elasticsearch: Ensure request URI is always prefixed with "/"
  AbstractElasticIndex: Factor out more variants of {post,perform}Request
  rest-api-projects: Fix "unterminated listing block" warning
  config-gerrit: Fix "invalid reference: database.h2.cachesize" warning
  Bazel: Specify name for downloaded file to http_file starlark rule
  Set version to 2.14.14-SNAPSHOT
  CreateProject: Provide signed push option on project creation
  Revert "AsyncReceiveCommits: Move ReceiveCommits into Worker"

Change-Id: I839334906060534e8dd9bd2658c6eb57ccd79c69
2018-09-27 16:45:10 +09:00

212 lines
6.9 KiB
Plaintext
Raw Blame History

= 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
---------
View Git Blame Copy Permalink