David Shevitz | 6493b2f | 2017-08-03 14:53:29 -0700 | [diff] [blame] | 1 | = Changes |
| 2 | |
| 3 | A change represents a single commit under review. Each change is identified |
| 4 | by a <<change-id>>. |
| 5 | |
| 6 | Multiple git commits can share the same Change-Id, allowing you to update a |
| 7 | change as you receive feedback through the code review process. In Gerrit, |
| 8 | commits that share the same Change-Id are referred to as _patch sets_. When a |
| 9 | change is approved, only the latest version of a commit is submitted to the |
| 10 | repository. |
| 11 | |
| 12 | You can view a specific change using Gerrit's Review screen. This screen |
| 13 | provides 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ół | 13bac47 | 2020-09-17 16:07:50 +0200 | [diff] [blame] | 17 | * Comments |
David Shevitz | 6493b2f | 2017-08-03 14:53:29 -0700 | [diff] [blame] | 18 | * Votes on link:config-labels.html[Review Labels] |
| 19 | * The <<change-id>> |
| 20 | |
| 21 | [[change-properties]] |
| 22 | == Change properties |
| 23 | |
| 24 | When you open a change in Gerrit, the Review screen displays a number of |
| 25 | properties 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 Kempin | 60fcf2d | 2022-05-23 12:24:08 +0200 | [diff] [blame] | 37 | |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 |
| 40 | an action in the UI). |
| 41 | |
David Shevitz | 6493b2f | 2017-08-03 14:53:29 -0700 | [diff] [blame] | 42 | |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 |
| 47 | are 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 Pursehouse | 3727dba | 2018-09-27 12:57:37 +0900 | [diff] [blame] | 59 | |The <<submit-strategies,submit strategy>> for the change. |
David Shevitz | 6493b2f | 2017-08-03 14:53:29 -0700 | [diff] [blame] | 60 | |
| 61 | |Code Review |
| 62 | |Displays the Code Review status for the change. |
| 63 | |
| 64 | |=== |
| 65 | |
| 66 | In addition, Gerrit displays the status of any additional labels, such as |
| 67 | the Verified label, that have been configured for the server. See |
| 68 | link:config-labels.html[Review Labels] for more information. |
| 69 | |
| 70 | [[change-message]] |
| 71 | == Change Message |
| 72 | |
| 73 | Next to the list of change properties is the change message. This message |
| 74 | contains user-supplied information regarding what the change does. To modify |
| 75 | the change message, click the *Edit* link. |
| 76 | |
| 77 | By default, the change message contains the Change-Id. This ID contains a |
| 78 | permanent link to a search for that Change-Id in Gerrit. |
| 79 | |
| 80 | [[related-changes]] |
| 81 | == Related Changes |
| 82 | |
| 83 | In some cases, a change may be dependent on another change. These changes are |
| 84 | listed next to the change message. These related changes are grouped together in |
| 85 | several categories, including: |
| 86 | |
| 87 | * Relation Chain. These changes are related by parent-child relationships, |
David Pursehouse | 2919b01 | 2018-09-27 12:59:12 +0900 | [diff] [blame] | 88 | regardless of <<topic,topic>>. |
David Shevitz | 6493b2f | 2017-08-03 14:53:29 -0700 | [diff] [blame] | 89 | * Merge Conflicts. These are changes in which there is a merge conflict with |
| 90 | the current change. |
David Pursehouse | 2919b01 | 2018-09-27 12:59:12 +0900 | [diff] [blame] | 91 | * Submitted Together. These are changes that share the same <<topic,topic>>. |
David Shevitz | 6493b2f | 2017-08-03 14:53:29 -0700 | [diff] [blame] | 92 | |
| 93 | An arrow indicates the change you are currently viewing. |
| 94 | |
| 95 | [[topic]] |
| 96 | == Topics |
| 97 | |
| 98 | Changes can be grouped by topics. Topics make it easier to find related changes |
| 99 | by using the topic search operator. Changes with the same topic also appear in |
| 100 | the *Relation Chain* section of the Review screen. |
| 101 | |
| 102 | Grouping changes by topics can be helpful when you have several changes that, |
| 103 | when combined, implement a feature. |
| 104 | |
| 105 | Assigning a topic to a change can be done in the change screen or through a `git |
| 106 | push` command. |
| 107 | |
Albert Cui | acef5c9 | 2021-02-26 19:42:27 +0000 | [diff] [blame] | 108 | For more information about using topics, see the user guide: |
| 109 | link:cross-repository-changes.html[Submitting Changes Across Repositories by using Topics]. |
| 110 | |
David Shevitz | 6493b2f | 2017-08-03 14:53:29 -0700 | [diff] [blame] | 111 | [[submit-strategies]] |
| 112 | == Submit strategies |
| 113 | |
| 114 | Each project in Gerrit can employ a specific submit strategy. This strategy is |
| 115 | listed in the change properties section of the Review screen. |
| 116 | |
| 117 | The 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 |
| 125 | submitting the change. |
| 126 | |
| 127 | To submit a change, the change must be a strict superset of the destination |
| 128 | branch. |
| 129 | |
| 130 | |Merge If Necessary |
| 131 | |The default submit strategy. If the change being submitted is a strict superset |
| 132 | of the destination branch, then the branch is fast-forwarded to the change. If |
| 133 | not, a merge commit is automatically created at submit time. This is identical |
| 134 | to 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 |
| 138 | destination branch. This is identical to the `git merge --no-ff` command. |
| 139 | It is often used when users of the project want to be able to read the history |
| 140 | of 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 |
| 144 | creating a new commit on top of the current branch. |
| 145 | |
| 146 | When cherry picking a change, Gerrit automatically appends a short summary of |
| 147 | the change's approvals and a link back to the change. The committer header is |
| 148 | also set to the submitter, while the author header retains the original patch |
| 149 | set author. |
| 150 | |
| 151 | NOTE: Gerrit ignores dependencies between changes when using this submit type |
| 152 | unless `change.submitWholeTopic` is enabled and depending changes share the same |
| 153 | topic. This means submitters must remember to submit changes in the right order |
| 154 | when using this submit type. |
| 155 | |
| 156 | |Rebase if Necessary |
| 157 | |If the change being submitted is a strict superset of the destination branch, |
| 158 | the branch is fast-forwarded to the change. If not, the change is automatically |
| 159 | rebased 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 |
| 163 | forward is possible. This strategy is also similar to Cherry Pick; however, |
| 164 | Rebase Always does not ignore dependencies. |
| 165 | |
| 166 | |=== |
| 167 | |
| 168 | Any project owner can use the Project screen to modify the method Gerrit uses |
| 169 | to submit a change. |
| 170 | |
| 171 | [[change-id]] |
| 172 | == Change-Id |
| 173 | |
| 174 | Gerrit uses a Change-Id to identify which patch sets belong to the same review. |
| 175 | For example, you make a change to a project. A reviewer supplies some feedback, |
Jonathan Nieder | 988abed | 2018-04-25 17:54:54 -0700 | [diff] [blame] | 176 | which you address in an amended commit. By assigning the same Change-Id to both |
David Shevitz | 6493b2f | 2017-08-03 14:53:29 -0700 | [diff] [blame] | 177 | commits, Gerrit can attach those commits to the same change. |
| 178 | |
| 179 | Change-Ids are appended to the end of a commit message, and resemble the |
| 180 | following: |
| 181 | |
| 182 | .... |
| 183 | commit 29a6bb1a059aef021ac39d342499191278518d1d |
| 184 | Author: A. U. Thor <author@example.com> |
| 185 | Date: 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 | |
| 198 | Gerrit requires that the Change-Id is in the footer (last paragraph) of a |
| 199 | commit message. It can be combined with a Signed-off-by, CC, or other lines. For |
| 200 | instance, the previous example has a Change-Id, along with a Signed-off-by and |
| 201 | CC line. |
| 202 | |
| 203 | Notice that the Change-Id is similar to the commit id. To avoid confusing the |
| 204 | two, a Change-Id typically begins with an `I`. |
| 205 | |
| 206 | While there are several ways you can add a Change-Id, the standard |
| 207 | method uses git's link:cmd-hook-commit-msg.html[commit-msg hook] |
| 208 | to automatically add the Change-Id to each new commit. |
| 209 | |
Peter Collingbourne | 8cab933 | 2020-08-18 14:42:44 -0700 | [diff] [blame] | 210 | == The Link footer |
| 211 | |
| 212 | Gerrit also supports the Link footer as an alternative to the Change-Id |
| 213 | footer. A Link footer looks like this: |
| 214 | |
| 215 | .... |
| 216 | Link: https://gerrit-review.googlesource.com/id/Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b |
| 217 | .... |
| 218 | |
| 219 | The advantage of this style of footer is that it usually acts |
| 220 | as a link directly to the change's review page, provided that |
| 221 | the change has been uploaded to Gerrit. Projects such as the |
| 222 | link:https://www.kernel.org/doc/html/latest/maintainer/configure-git.html#creating-commit-links-to-lore-kernel-org[Linux kernel] |
| 223 | have a convention of adding links to commit messages using the |
| 224 | Link footer. |
| 225 | |
| 226 | If multiple changes have been uploaded to Gerrit with the same |
| 227 | change ID, for example if a change has been cherry-picked to multiple |
| 228 | branches, the link will take the user to a list of changes. |
| 229 | |
| 230 | The base URL in the footer is required to match the server's base URL. |
| 231 | If the URL does not match, the server will not recognize the footer |
| 232 | as a change ID footer. |
| 233 | |
| 234 | The link:cmd-hook-commit-msg.html[commit-msg hook] can be configured |
| 235 | to insert Link footers instead of Change-Id footers by setting the |
| 236 | property `gerrit.reviewUrl` to the base URL of the Gerrit server. |
| 237 | |
David Shevitz | 6493b2f | 2017-08-03 14:53:29 -0700 | [diff] [blame] | 238 | GERRIT |
| 239 | ------ |
| 240 | Part of link:index.html[Gerrit Code Review] |
| 241 | |
| 242 | SEARCHBOX |
| 243 | --------- |