Using Gerrit: Difference between revisions

From Lustre Wiki
Jump to navigation Jump to search
(→‎Requesting Patch Review: add mention of get_maintainers.pl script)
(→‎Submitting Patches for Review, Testing, and Landing: add in Requirements for Patch Submission)
(6 intermediate revisions by the same user not shown)
Line 17: Line 17:
     $ cd lustre-master
     $ cd lustre-master


This will create the master branch in your repository, which should never be modified. Typically in git, one creates a new local branch for each change being made. The branch is created based on one of the local, pristine branches follow the main development branches, usually the '''master'''. A new local branch is usually create using '''git checkout''':
This will create the master branch in your repository, which should never be modified. Typically with git, one creates a new local branch for each change being made, and a separate commit for each logical change. The branch is created based on one of the local, pristine branches that follows the main development branches, usually the <code>master</code> branch. A new local branch is usually create using <code>git checkout -b</code>:


     $ git checkout -b my-brilliant-idea master
     $ git checkout -b my_brilliant_idea master


This creates a new branch from '''master''' called '''my-brilliant-idea''', and also makes it the current branch.
This creates a new branch from <code>master</code> called <code>my-brilliant_idea</code>, and also makes it the current branch.  This keeps independent changes separated from each other, simplifying patch management and landing.


In order ensure that the commit description contains the correct name and email address for you, it is possible to specify this directly to Git creating or modifying the '''$HOME/.gitconfig''' file in your home directory (preferred), or in the '''.git/config''' file in the local repository. This only needs to be done one time, or once per checkout, if done in the local repository.
In order ensure that the commit description contains the correct name and email address for you, it is possible to specify this directly to Git creating or modifying the <code>$HOME/.gitconfig</code> file in your home directory (preferred), or in the <code>.git/config</code> file in the local repository (e.g. if you are using a different email address for submissions to this repository). This only needs to be done one time, or once per checkout, if done in the local repository.


     [user]
     [user]
Line 31: Line 31:
         url = ssh://[email protected]:29418/fs/lustre-release  
         url = ssh://[email protected]:29418/fs/lustre-release  


Now all '''git commit''' commands in any repository will use this name/email regardless of which user account is used to do the modifications, if using '''$HOME/.gitconfig''' file. If you want to specify a different name or email for a specific repository, it is possible to add this information to the '''.git/config''' file in that specific repository. See commit comment details below.  The optional '''[remote "review"]''' block adds an alias for the remote Gerrit repository to simplify pulling updates and pushing patches, and should only be added in the local '''.git/config''' file.
Now all <code>git commit</code> commands in any repository will use this name/email regardless of which user account is used to do the modifications.  The optional <code>[remote "review"]</code> block adds an alias for the remote Gerrit repository to simplify pulling updates and pushing patches, and should only be added in the local <code>.git/config</code> file.


For Lustre patches, the code needs to follow specific [[Lustre Coding Style Guidelines]] (which is basically the Linux kernel CodingStyle, with extra details for Lustre), as do the [[Commit Comments]] for each patch. In order to help maintain the uniform code style, Lustre-specific Git commit hooks should be installed in all Lustre development trees. In the top-level directory of the checked-out Lustre repository install the hooks using:
For Lustre patches, the code needs to follow specific [[Lustre Coding Style Guidelines]] (which is basically the Linux kernel CodingStyle, with extra details for Lustre), as do the [[Commit Comments]] for each patch. In order to help maintain the uniform code style, Lustre-specific Git commit hooks should be installed in all Lustre development trees. In the top-level directory of the checked-out Lustre repository install the hooks using:
Line 38: Line 38:
     $ ln -sf ../../contrib/git-hooks/prepare-commit-msg .git/hooks/
     $ ln -sf ../../contrib/git-hooks/prepare-commit-msg .git/hooks/


This will run the '''contrib/git-hooks/prepare-commit-msg''' script from the currently-checked-out Lustre tree to run the modifications through the '''contrib/git-hooks/checkpatch.pl''' script for style errors, and the '''contrib/git-hooks/commit-msg''' script afterward to verify the format of the commit message itself.  The format of commit comments is described below.
This will run the <code>contrib/git-hooks/prepare-commit-msg</code> script from the currently-checked-out Lustre tree to run the modifications through the <code>contrib/git-hooks/checkpatch.pl</code> script for style errors, and the <code>contrib/git-hooks/commit-msg</code> script afterward to verify the format of the commit message itself.  The format of commit comments is described below.


Once you've made the change, and you want to save the code for testing and reviewed by others, you commit the change. Before you commit in Git, you need to identify which new or changed file(s) you want to commit using '''git add <filename>''' for a specific filename, or '''git add -u''' for all updated files. If you haven't added any new files, and you want to commit all the files that you have changed (which is the usual case), then you can use the '''-a''' option to commit:
Once you've made the change, and you want to save the code for testing and reviewed by others, you commit the change. Before you commit in Git, you need to identify which new or changed file(s) you want to commit using <code>git add <filename></code> for a specific filename, or <code>git add -u</code> for all updated files. If you haven't added any new files, and you want to commit all the files that you have changed (which is the usual case), then you can use the <code>-a</code> option to commit:


     $ git commit -avs
     $ git commit -avs


This will put you into an editor to update your commit comment, and when you save it will commit the change locally. The '''-v''' option appends the diff to the edit buffer so you can review what is about to be committed.  This is very useful to verify that you are committing what you want to commit, and not changes or files that are unrelated to the current change.  The '''-s''' option adds a '''[[Signed-off-by]]:''' line to the commit message, which is required for all patches submitted to Lustre.
This will put you into an editor to update your commit comment, and when you save it will commit the change locally. The <code>-v</code> option appends the diff to the edit buffer so you can review what is about to be committed.  This is very useful to verify that you are committing what you want to commit, and not changes or files that are unrelated to the current change.  The <code>-s</code> option adds a <code>[[Signed-off-by]]:</code> line to the commit message, which is required for all patches submitted to Lustre.


It is best to commit relatively frequently to keep your changes limited to a single fix. If you notice other, unrelated, issues that need to be fixed, then it's best to put them in a separate commit on a separate branch, so they can be submitted to Gerrit independently for review, testing, and landing. The '''stash''' command is handy for this:
It is best to commit relatively frequently to keep your changes limited to a single fix. If you notice other, unrelated, issues that need to be fixed, then it's best to put them in a separate commit on a separate branch, so they can be submitted to Gerrit independently for review, testing, and landing. The <code>stash</code> command is handy for this:


     # While fixing a bug you notice something evil that must be fixed.
     # While fixing a bug you notice something evil that must be fixed.
Line 53: Line 53:


     # Next go create a new branch and purge the ugliness you just discovered:
     # Next go create a new branch and purge the ugliness you just discovered:
     $ git checkout -b my-eyes-are-bleeding master
     $ git checkout -b my-eyes_are_bleeding master
     \{ fix ugliness \}
     \{ fix ugliness \}
     $ git commit -av
     $ git commit -av


     # Now go back to what you were working on:
     # Now go back to what you were working on:
     $ git checkout my-brilliant-idea
     $ git checkout -
     $ git stash pop
     $ git stash pop


===Formatting Git Commit Comments===
===Formatting Git Commit Comments===


Having good commit comments helps everyone that is working on the code. See [[Commit Comments]] for a detailed description of the commit comment style. If your commit does not include the Change-Id: line as described below (which should be added automatically by the '''commit-msg''' hook, see above), the patch will be automatically rejected at submission time.
Having good commit comments helps everyone that is working on the code. See [[Commit Comments]] for a detailed description of the commit comment style.


Sample Commit message:
Sample Commit message:


     LU-nnnn component: short description of change under 62 columns
     LU-nnnnn component: short description of change under 62 columns
      
      
     A more detailed explanation of the change being made.  This can be as
     A more detailed explanation of the change being made.  This can be as
Line 81: Line 81:
     a description of how they were measured.
     a description of how they were measured.
      
      
     Wrap lines at 70 columns or less.
     Wrap lines at 70 columns or fewer.
      
      
     Other useful commit message labels go here.
     Other useful commit message labels go here.
      
      
    Fixes: 1234567890ab ("LU-nnnn comp: old patch being fixed by this one")
     Signed-off-by: Random J Developer <[email protected]>
     Signed-off-by: Random J Developer <[email protected]>
     Change-Id: Ica9ed1612eab0c4673dee088f8b441d806c64932
     Change-Id: Ica9ed1612eab0c4673dee088f8b441d806c64932
Line 90: Line 91:
===Adding the Change-Id field===
===Adding the Change-Id field===


Gerrit requires all changes to have the '''Change-Id:''' field, or it will be rejected. It should be added automatically by the '''.git/hooks/commit-msg''' script. See [[Commit Comments]] for a detailed description of the '''Change-Id:''' field.
Gerrit requires all changes to have the <code>Change-Id:</code> field, or it will be rejected. It should be added automatically by the <code>.git/hooks/commit-msg</code> script. See [[Commit Comments]] for a detailed description of the <code>Change-Id:</code> field.


==Submitting Patches for Review, Testing, and Landing==
==Submitting Patches for Review, Testing, and Landing==
All patches that land on the main release branches in the <code>fs/lustre-release</code> repository must conform to the [[Lustre_Coding_Guidelines]], pass the standard Lustre regression tests. All patches should be associated with a Lustre Jira ticket, and contain a commit message the fully meets the [[Commit_Comments|Commit Comment Format Requirements]]. Bug fixes should include additional regression tests to ensure the problem is fixed, since the presence of the bug indicates that no test is covering this functionality, and the test will prevent the bug from being reintroduced in the future. Feature patches should include new regression tests to exercise the feature, and potentially performance or load tests as appropriate for the change. All changes submitted to the <code>fs/lustre-release</code> repository will be tested automatically with the Lustre regression tests in lustre/tests and a link to the test results (saved in [https://testing.whamcloud.com/ Maloo]) and a pass/fail review comment will be added to the Gerrit change. For additional tests run outside of autotest, the results can either be sent to Maloo manually, or test results can be posted into the Jira ticket associated with the patch.
Any patches that require updates to the Lustre manual will also need to submit documentation updates when the patch is ready for submission. See the [[Lustre_Manual_Changes]] page for more details.
Any additional feature testing that cannot be covered by the existing or added automated Lustre tests must also be documented with a clear, step-by-step test plan, and arrangements must be made with the Lustre test team to execute these plans.


A change request is created by pushing a patch to a special branch on the Gerrit repository. To create an change request for a patch in your local branch the local commit (or series of commits) needs to be pushed to the Gerrit review repository.
A change request is created by pushing a patch to a special branch on the Gerrit repository. To create an change request for a patch in your local branch the local commit (or series of commits) needs to be pushed to the Gerrit review repository.


It is possible to push a series of dependent commits from a local branch in this same way, and each one will create a separate change in Gerrit. Patch series should be used to split complex code changes that are implementing a single larger feature into chunks that are easier to understand, review, test, and land. Changes in a patch series will be dependent on each other, so if one patch needs to be refreshed after a review or test failure it will cause all of the later patches to be refreshed also. That will clear all of the review and test results and restart testing on all of the patches.
If there are a series of '''dependent''' changes being made to the code (e.g. code style fixes, renaming some functions, adding function parameters, moving code from one file to another, making the actual fix for a bug, making some additional fixes to other defects found during coding), these should all go into separate patches for [https://wiki.whamcloud.com/display/PUB/Patch+Inspections+for+Developers+and+Inspectors Patch Inspections] and testing. Having a series of smaller patches, each of which makes a single clearly understood change, speeds up inspection significantly and means those changes will land sooner. Ordering uncontroversial and easy-to-inspect changes first in a patch series ensures that they are only inspected a single time, and can land quickly. Ordering complex changes at the end of the patch series ensures that if changes are requested by the inspectors for these patches, the earlier ones do not need to be re-inspected and re-tested for each update. Following this patch submission model speeds up patch landing, and reduces the burden on the patch inspector, and test systems, and reduces the time that the patch submitter needs to spend waiting or rebasing in order to get their patches accepted.


Patch series should ''not'' be used for code that was written and then had a series of bug fixes applied to it after local testing. The later (local) bug fixes should be squashed into the original change before submission. Note that each patch in a series must build and test properly before it can be landed, so compile warnings or test failures in the middle of a patch series are not allowed.
Patch series should '''not''' be used for code that was written and then had a series of bug fixes applied to it after local testing. The later (local) bug fixes should be squashed into the original change before submission. Note that each patch in a series '''must build and pass testing''' before it can be landed, so compile warnings or test failures in the middle of a patch series are not allowed.


If you have a series of ''independent'' commits to be reviewed, each one should be in a separate local branch and pushed separately to Gerrit. This allows the patches to be reviewed, tested, and landed independently, and will avoid the overhead and delay of repeatedly reviewing, building, and testing patches that are only refreshed because of an earlier (unrelated) patch in a series being modified.
If you have a series of ''independent'' commits to be reviewed, each one should be in a separate local branch and pushed separately to Gerrit. This allows the patches to be reviewed, tested, and landed independently, and will avoid the overhead and delay of repeatedly reviewing, building, and testing patches that are only refreshed because of an earlier (unrelated) patch in a series being modified.
Line 104: Line 111:
     $ git push ssh://[email protected]:29418/fs/lustre-release HEAD:refs/for/master
     $ git push ssh://[email protected]:29418/fs/lustre-release HEAD:refs/for/master


for the master branch of the '''fs/lustre-release''' repo, or:
for the master branch of the <code>fs/lustre-release</code> repo, or:


     $ git push ssh://[email protected]:29418/fs/lustre-release HEAD:refs/for/b2_11
     $ git push ssh://[email protected]:29418/fs/lustre-release HEAD:refs/for/b2_12


for the '''b2_11''' branch of the '''fs/lustre-release''' repo, or:
for the <code>b2_12</code> branch of the <code>fs/lustre-release</code> repo, or:


     $ git push ssh://[email protected]:29418/tools/e2fsprogs HEAD:refs/for/master-lustre
     $ git push ssh://[email protected]:29418/tools/e2fsprogs HEAD:refs/for/master-lustre


for the '''master-lustre''' branch of the '''tools/e2fsprogs''' repo.
for the <code>master-lustre</code> branch of the <code>tools/e2fsprogs</code> repo.


For convenience, you can add this to your '''~/.ssh/config''' file:
For convenience, you can add this to your <code>~/.ssh/config</code> file:


     Host review
     Host review
Line 122: Line 129:
         IdentityFile ~/.ssh/my-key-id_rsa
         IdentityFile ~/.ssh/my-key-id_rsa


Creating a review request for a change against master (assuming the remote alias has been added to ssh config):
Creating a review request for a change against master (assuming the remote alias has been added to <code>~/.ssh/config</code>):


     $ git push ssh://review/fs/lustre-release HEAD:refs/for/master
     $ git push ssh://review/fs/lustre-release HEAD:refs/for/master
Line 132: Line 139:
===Automatically Building and Testing a Patch===
===Automatically Building and Testing a Patch===


When the patch has been pushed to the Gerrit '''fs/lustre-review''' repository, it will print a URL for that change set that should be added to the Jira ticket for tracking.  This should now happen automatically.
When the patch has been pushed to the Gerrit <code>fs/lustre-review</code> repository, it will print a URL for that change set that should be added to the Jira ticket for tracking.  This should now happen automatically.


All patches submitted to Gerrit will be built automatically by Jenkins for a number of different distro and kernel versions. Currently for the master branch this includes RHEL6 i686/x86_64 client/server, RHEL7 x86_64 client, and SLES11 x86_64 client/server. The success/failure of these builds will be posted to the change in Gerrit as a link to the Jenkins build artifacts.
All patches submitted to Gerrit will be built automatically by Jenkins for a number of different distro and kernel versions. Currently for the master branch this includes RHEL7 x86_64 client/server, Ubuntu x86_64/ARM clients, and SLES12 x86_64 client/server. The success/failure of these builds will be posted to the change in Gerrit as a link to the Jenkins build artifacts.


After a successful build on all of the configurations, one or more of the configurations will be regression tested automatically, and a link to the test results in Maloo will be posted to Gerrit. It is also possible to [[Using Maloo|manually post test results to Maloo]] from your own testing.  Normally, there are four separate test sessions run for patches submitted to the master branch.  The majority of the test sessions will be enforced, which means that they must pass in order to land the patch, but in some cases they may be optional and are not required to pass before landing.
After a successful build on all of the configurations, one or more of the configurations will be regression tested automatically, and a link to the test results in Maloo will be posted to Gerrit. It is also possible to [https://wiki.whamcloud.com/display/PUB/Changing+Test+Parameters+with+Gerrit+Commit+Messages add special testing requests using the Test-Parameters: label] when the patch is submitted.  Normally, there are ten separate test sessions run for patches submitted to the master branch.  The majority of the test sessions will be enforced, which means that they '''must''' pass in order to land the patch.  In some cases test sessions may be marked '''optional''' and are not ''required'' to pass before landing (e.g. sessions for new distros/kernels, new features, etc.), but it is still desirable to check if they are failing due to issues introduced by the patch to avoid test regressions.


Automated regression testing for each patch should normally pass.  In some cases it might fail for a variety of reasons, such as a bug in the patch, an intermittent test failure that is present in the existing code, problems with the testing system, etc.  In '''all failure cases''', the Maloo test failure(s) should be investigated as to the root cause.  Once the test failure is identified in Maloo, the failed test result should either be linked ('''Associate bug''') to an existing LU ticket in Jira, or if necessary a new Jira ticket with details of the failure should be filed ('''Raise bug'''), and a comment added to Gerrit with the JIRA LU ticket number.  At this point the test could be resubmitted, if there are no other problems with the patch, or it can be refreshed if there are review comments that need to be addressed (per below).
Automated regression testing for each patch should normally pass.  In some cases it might fail for a variety of reasons, such as a bug in the patch, an intermittent test failure that is present in the existing code, problems with the testing system, etc.  '''In all failure cases''', the Maloo test failure(s) should be investigated as to the root cause.  Once the cause of the test failure is identified in Maloo, the failed test result should either be linked (via <code>[Associate bug]</code>) to an existing LU ticket in Jira, or if necessary a new Jira ticket with details of the failure should be filed (via <code>[Raise bug]</code>), and a comment added to Gerrit with the JIRA LU ticket number.  At this point the test could be resubmitted, if there are no other problems with the patch, or it can be refreshed if there are defects found in the patch and/or review comments that need to be addressed (per below).


===Requesting Patch Review===
===Requesting Patch Review===


In order to actually get a patch landed, you need to request at least two reviews in Gerrit for the patch. This is done by visiting the [https://review.whamcloud.com/ Gerrit web page] for the change (at the URL returned when the commit was pushed, or it can be found from your home page after logging in). Enter the name or email address for the reviewer and click the '''Add...''' button in the top right corner.
In order to actually get a patch landed, you need to request at least two reviews in Gerrit for the patch. This is done by visiting the [https://review.whamcloud.com/ Gerrit web page] for the change (at the URL returned when the commit was pushed, or it can be found from your home page after logging in). Enter the name or email address for the reviewer and click the <code>[Add...]</code> button in the top right corner.


If you are unsure of who should be the reviewer of your patch, you can use the '''get_maintainer.pl''' script to get a list of potential candidates (the commit hash is optional, just to give a concrete example here) based on the '''MAINTAINERS''' file and recent commits to the modified files:
If you are unsure of who should be the reviewer of your patch, you can use the <code>get_maintainer.pl</code> script to get a list of potential candidates.  The commit hash shown in the example is optional, just to give a concrete example here) based on the <code>MAINTAINERS</code> file and recent commits to the modified files, otherwise it will examine the top patch on the branch:


     $ git show 8b364fbd6bd9e0088440e6d6837861a641b923a0 | ./contrib/scripts/get_maintainer.pl
     $ git show 8b364fbd6bd9e0088440e6d6837861a641b923a0 | ./contrib/scripts/get_maintainer.pl
Line 155: Line 162:
     Alexander Boyko <[email protected]> (authored:1/6=17%,added_lines:11/65=17%,removed_lines:16/82=20%)
     Alexander Boyko <[email protected]> (authored:1/6=17%,added_lines:11/65=17%,removed_lines:16/82=20%)


The list is '''not''' always providing the best candidates, since it doesn't know the difference between someone making a cosmetic patch and the experts in the code, but at least it can provide a starting point.  Usually it makes sense to include the top 2-3 people, in particular anyone marked '''reviewer''' for that code.  The reported list of developers will change over time, as new commits are added to the affected files.
The list is '''not''' always providing the best candidates, since it doesn't know the difference between someone making a cosmetic patch and the experts in the code, but at least it can provide a starting point.  Usually it makes sense to include the top 2-3 people, in particular anyone marked <code>reviewer</code> for that code.  The reported list of developers will change over time, as new commits are added to the affected files.




In conjunction with the two review requests, the patch has to successfully build on all supported architecture/distro combinations, and pass the automatic testing (as reported by [[Using Maloo|Maloo]]). Once the patch has passed two reviews ('''+1''' or '''+2 Review''' from reviewers that are ''not the original developer''), built correctly ('''+1 Verified''' from Jenkins), and has passed autotest ('''+1 Verified''' from Maloo) the patch will automatically appear in the Gatekeeper's list of patches to land.
In conjunction with the two review requests, the patch has to successfully build on all supported architecture/distro combinations, and pass the automatic testing (as reported by [[Using Maloo|Maloo]]). Once the patch has passed two reviews (<code>Reviewed: +1</code> or <code>Reviewed: +2</code> from reviewers that are ''not the change owner''), built correctly (<code>Verified: +1 </code> from Jenkins), and has passed autotest (<code>Verified: +1</code> from Maloo) the patch will automatically appear in the Gatekeeper's list of patches to land.


''It is the responsibility of the patch submitter'' to request the reviewers to look at the patch, to check for build/test failures and annotate them correctly, and to refresh the patch after addressing review, build, or test issues.  If this is not happening in a timely manner, one option is adding a comment into the patch to alert the reviewers that the patch needs attention.
''It is the responsibility of the patch submitter'' to request the reviewers to look at the patch, to check for build/test failures and annotate them correctly, and to refresh the patch after addressing review, build, or test issues.  If this is not happening in a timely manner, one option is adding a comment into the patch to alert the reviewers that the patch needs attention.
Line 164: Line 171:
===Updating Patches After Review===
===Updating Patches After Review===


Gerrit makes it easy to update a patch after review, and doing this allows reviewers to see differences between the patches so they only need to review the changes between the patches instead of having to review the entire patch again. Also, the original inline comments are maintained and moved to the new patches. The key to keeping updated review requests linked to the original patch is the '''Change-Id:''' field in the commit comment - this is what Gerrit uses to find the original patch to update.
Gerrit makes it easy to update a patch after review, and doing this allows reviewers to see differences between the patches so they only need to review the changes between the patches instead of having to review the entire patch again. Also, the original inline comments are maintained and moved to the new patches. The key to keeping updated review requests linked to the original patch is using the same <code>Change-Id:</code> field in the commit comment - this is what Gerrit uses to find the original patch to update.


A critical thing to point out is that you must submit a new version of the entire patch - not just an update to the patch.
A critical thing to point out is that you must submit a new version of the entire patch - not just an update to the patch.


The easiest way to update the most recent commit (which is often the one you want to update), is to use "'''git commit --amend -a'''".  This will "add" any modifications in the current repository and merge them into the last commit.  If there are no changes, or "'''-a'''" is not used, this will just allow you to edit the most recent commit message.  This is useful if you don't have a '''Change-Id:''' line in your commit message (because you didn't install the '''commit-msg''' hook, see [#Formatting Git Commit Comments] above), but a '''Change-Id:''' was added automatically by Gerrit.  You can copy the '''Change-Id:''' from the Gerrit web page for that change and paste it into the amended commit message.  Typically, the updated patch should also be rebased to the tip of the current branch before pushing it again, to ensure that it does not conflict with other changes that may have been landed since the patch was first developed.
The easiest way to update the most recent commit (which is often the one you want to update), is to use "<code>git commit --amend -a</code>".  This will "add" any modifications in the current repository and merge them into the last commit.  If there are no changes, or <code>-a</code> is not used, this will just allow you to edit the most recent commit message.  This is useful if you don't have a <code>Change-Id:</code> line in your commit message (because you didn't install the <code>commit-msg</code> hook, see [#Formatting Git Commit Comments] above), but a <code>Change-Id:</code> was added automatically by Gerrit.  You can copy the <code>Change-Id:</code> from the Gerrit web page for that change and paste it into the amended commit message.  Typically, the updated patch should also be rebased to the tip of the current branch before pushing it again, to ensure that it does not conflict with other changes that may have been landed since the patch was first developed.


Another way of modifying a series of existing changes is to use "'''git rebase -i <parent-branch>'''". Interactive rebase will display a list of patches in an editor, and you can reorder the patches, "'''edit'''" the patch, "'''reword'''" the commit comments, and "'''squash'''" two patches into a single patch. See the help text in the commit message editor window for more information.  
Another way of modifying a series of existing changes is to use "<code><nowiki>git rebase -i <parent-branch></nowiki></code>". Interactive rebase will display a list of patches in an editor, and you can reorder the patches, "<code>edit</code>" the patch, "<code>reword</code>" the commit comments, and "<code>squash</code>" two patches into a single patch. See the help text in the commit message editor window for more information.  


Once the change has been updated, push your branch to Gerrit again, and the original request will be updated with the new version of the patch.
Once the change has been updated, push your branch to Gerrit again, and the original request will be updated with the new version of the patch.


===(Re-)Basing One Change on Another Change===
===Basing One Change on Another Unlanded Change===


It is possible to base a new change, or rebase an existing change, on an uncommitted patch in Gerrit. This might be useful if both changes are impacting the same code, and one change is clearly dependent on another for some reason, or if they will cause conflicts when merged and a decision is made to land them in a specific order. It is desirable to break a patch into multiple functionally-separate commits for several reasons, see [[Requirements for patch submission]]. If the patches are truly ''independent'' (i.e. no overlapping changes to the same files, no dependent functions, etc), then those patches should be submitted in separate branches, and this section does not apply.
It is possible to base a new change, or rebase an existing change, on an uncommitted patch in Gerrit. This might be useful if both changes are impacting the same code, and one change is clearly dependent on another for some reason, or if they will cause conflicts when merged and a decision is made to land them in a specific order. It is desirable to break a patch into multiple functionally-separate commits for several reasons. If the patches are truly ''independent'' (i.e. no overlapping changes to the same files, no dependent functions, etc), then those patches should be submitted in separate branches, and this section does not apply.


If both patches are being developed by the same person, the easiest way to have a series of ''dependent'' changes is to commit them into separate patches order on the same branch. Then, when a change is made to any patch on that branch, all of the dependent changes will also be resubmitted to Gerrit so that they will be ready to land when the earlier patches are merged.
If both patches are being developed by the same person, the easiest way to have a series of ''dependent'' changes is to commit them into separate patches order on the same branch. Then, when a change is made to any patch on that branch, all of the dependent changes will also be resubmitted to Gerrit so that they will be ready to land when the earlier patches are merged.


If updates or fixes need to be made to one of the patches, these updates should be merged into the original commit where the code was added, rather than being an additional patch at the end of the series. This can be done by running "'''git rebase -i <parent-branch>'''", then marking a particular patch for '''edit'''. That will cause the earlier patches in the series up to the to be applied, then stop for interactive editing/testing of that patch. Once the patch has been updated, run '''git add -u''' to include the new updates into this patch, and '''git rebase --continue''' to merge the updates into the existing patch and continue the rebase process.
If updates or fixes need to be made to one of the patches, these updates should be merged into the original commit where the code was added, rather than being an additional patch at the end of the series. This can be done by running "<code>git rebase -i <parent-branch></code>", then marking a particular patch for <code>edit</code>. That will cause the earlier patches in the series up to the to be applied, then stop for interactive editing/testing of that patch. Once the patch has been updated, run "<code>git add -u</code>" to include the new updates into this patch, and "<code>git rebase --continue</code>" to merge the updates into the existing patch and continue the rebase process.


In the case where changes need to be based on a patch from another developer, it is possible to check out the desired patch from Gerrit using one of the supplied Git URLs in the '''Download''' section under the patchset. Select the '''Checkout''' options, then copy the URL and paste it at the command prompt of a previously checked-out Lustre tree.  For example to fetch patchset 16 from [https://review.whamcloud.com/1264 Change 1264], create a branch for it, and then create a new branch for your local changes based on that change, use:
In the case where changes need to be based on a patch from another developer, it is possible to check out the desired patch from Gerrit using one of the supplied Git URLs in the <code>[Download v]</code> section in the top right corner of the change page. Select the <code>Checkout</code> options, then copy the URL and paste it at the command prompt of a previously checked-out Lustre tree.  For example to fetch patchset 16 from [https://review.whamcloud.com/1264 Change 1264], create a branch for it, and then create a new branch for your local changes based on that change, use:


     [lustre]$ git fetch http://review.whamcloud.com/p/fs/lustre-release refs/changes/64/1264/16 && git checkout FETCH_HEAD
     [lustre]$ git fetch http://review.whamcloud.com/p/fs/lustre-release refs/changes/64/1264/16 && git checkout FETCH_HEAD
Line 190: Line 197:
     [lustre]$ git commit -a
     [lustre]$ git commit -a


Any changes in the '''b_1264_my_changes''' will be based on top of those of '''b_1264'''. When '''b_1264_my_changes''' is pushed to Gerrit, it will have a dependency on change 1264, so it will not be able to land until change 1264 itself is landed.  It is typically not desirable to locally rebase the '''b_1264''' branch to a new version of master or modify it, or it will cause the other developer's patch to be updated in Gerrit, and lose its existing review and test results.  However, in some cases this ''is'' desirable, and Gerrit allows a user other than the original author to push an updated version of the patch (using the same '''Change-Id:''' label) in case there is a problem with the original patch (e.g. no longer applies, has a bug, etc).
Any changes in the <code>b_1264_my_changes</code> will be based on top of those of <code>b_1264</code>. When <code>b_1264_my_changes</code> is pushed to Gerrit, it will have a dependency on change 1264, so it will not be able to land until change 1264 itself is landed.  It is typically not desirable to locally rebase the <code>b_1264</code> branch to a new version of master or modify it, or it will cause the other developer's patch to be updated in Gerrit, and lose its existing review and test results.  However, in some cases this ''is'' desirable, and Gerrit allows a user other than the original author to push an updated version of the patch (using the same <code>Change-Id:</code> label) in case there is a problem with the original patch (e.g. no longer applies, has a bug, etc).


If you already have the changes in a local branch (e.g. '''b_my_changes''') and want to rebase that branch on top of another uncommitted patch from Gerrit, the process is similar:
If you already have the changes in a local branch (e.g. <code>b_my_changes</code>) and want to rebase that branch on top of another uncommitted patch from Gerrit, the process is similar:


     [lustre]$ git fetch http://review.whamcloud.com/p/fs/lustre-release refs/changes/64/1264/16 && git checkout FETCH_HEAD
     [lustre]$ git fetch http://review.whamcloud.com/p/fs/lustre-release refs/changes/64/1264/16 && git checkout FETCH_HEAD
Line 205: Line 212:
This is normally done by the branch maintainer, but is recorded here for future reference.
This is normally done by the branch maintainer, but is recorded here for future reference.


Switch to the branch you want to create a branch in (normally '''master''' or a release branch like '''b2_11''').
Switch to the branch you want to create a branch in (normally <code>master</code> or a release branch like <code>b2_12</code>).


Create the tag with:
Create the tag with:
Line 217: Line 224:


     $ git push review TAG_NAME
     $ git push review TAG_NAME
==Searching on Gerrit==
This is covered on the page: [https://wiki.whamcloud.com/display/PUB/Useful+Gerrit+Searches Useful Gerrit Searches]


[[Category:Development]]
[[Category:Development]]

Revision as of 15:08, 18 June 2020

About Gerrit

Gerrit is primarily a code review tool, but can also be used to track the status of patch as it is build tested, and finally merged to a branch. Developers submit patches to Gerrit using git, and there is a rich browser interface for performing code reviews. Reviewers can also pull the change directly to their own Git repository and review the change locally.

To upload changes to Gerrit, you must first register and add an ssh key to your account, then send an email request for push permission to [email protected].

Gerrit can host many git repositories, and of course each of those repositories can contain many branches.

This page describes the technical process of pushing a patch for review. In addition to the pushing a patch to Gerrit, there is an additional process for Submitting Changes that should be followed in order to ensure that your patch will be accepted for landing.

Managing Changes in Git

Whole books could be written about this topic, and there plenty of online tutorials on the web that explain this in more detail and suggest other methods of managing changes. However, this distilled version is (hopefully) enough to get started.

To make an initial checkout of the master Lustre Git repository:

   $ git clone -b master git://git.whamcloud.com/fs/lustre-release.git lustre-master
   $ cd lustre-master

This will create the master branch in your repository, which should never be modified. Typically with git, one creates a new local branch for each change being made, and a separate commit for each logical change. The branch is created based on one of the local, pristine branches that follows the main development branches, usually the master branch. A new local branch is usually create using git checkout -b:

   $ git checkout -b my_brilliant_idea master

This creates a new branch from master called my-brilliant_idea, and also makes it the current branch. This keeps independent changes separated from each other, simplifying patch management and landing.

In order ensure that the commit description contains the correct name and email address for you, it is possible to specify this directly to Git creating or modifying the $HOME/.gitconfig file in your home directory (preferred), or in the .git/config file in the local repository (e.g. if you are using a different email address for submissions to this repository). This only needs to be done one time, or once per checkout, if done in the local repository.

   [user]
       name = Random J. Developer
       email = [email protected]
   [remote "review"]
       url = ssh://[email protected]:29418/fs/lustre-release 

Now all git commit commands in any repository will use this name/email regardless of which user account is used to do the modifications. The optional [remote "review"] block adds an alias for the remote Gerrit repository to simplify pulling updates and pushing patches, and should only be added in the local .git/config file.

For Lustre patches, the code needs to follow specific Lustre Coding Style Guidelines (which is basically the Linux kernel CodingStyle, with extra details for Lustre), as do the Commit Comments for each patch. In order to help maintain the uniform code style, Lustre-specific Git commit hooks should be installed in all Lustre development trees. In the top-level directory of the checked-out Lustre repository install the hooks using:

   $ ln -sf ../../contrib/git-hooks/commit-msg .git/hooks/
   $ ln -sf ../../contrib/git-hooks/prepare-commit-msg .git/hooks/

This will run the contrib/git-hooks/prepare-commit-msg script from the currently-checked-out Lustre tree to run the modifications through the contrib/git-hooks/checkpatch.pl script for style errors, and the contrib/git-hooks/commit-msg script afterward to verify the format of the commit message itself. The format of commit comments is described below.

Once you've made the change, and you want to save the code for testing and reviewed by others, you commit the change. Before you commit in Git, you need to identify which new or changed file(s) you want to commit using git add <filename> for a specific filename, or git add -u for all updated files. If you haven't added any new files, and you want to commit all the files that you have changed (which is the usual case), then you can use the -a option to commit:

   $ git commit -avs

This will put you into an editor to update your commit comment, and when you save it will commit the change locally. The -v option appends the diff to the edit buffer so you can review what is about to be committed. This is very useful to verify that you are committing what you want to commit, and not changes or files that are unrelated to the current change. The -s option adds a Signed-off-by: line to the commit message, which is required for all patches submitted to Lustre.

It is best to commit relatively frequently to keep your changes limited to a single fix. If you notice other, unrelated, issues that need to be fixed, then it's best to put them in a separate commit on a separate branch, so they can be submitted to Gerrit independently for review, testing, and landing. The stash command is handy for this:

   # While fixing a bug you notice something evil that must be fixed.
   # First set your current work aside:
   $ git stash
   # Next go create a new branch and purge the ugliness you just discovered:
   $ git checkout -b my-eyes_are_bleeding master
   \{ fix ugliness \}
   $ git commit -av
   # Now go back to what you were working on:
   $ git checkout -
   $ git stash pop

Formatting Git Commit Comments

Having good commit comments helps everyone that is working on the code. See Commit Comments for a detailed description of the commit comment style.

Sample Commit message:

   LU-nnnnn component: short description of change under 62 columns
   
   A more detailed explanation of the change being made.  This can be as
   detailed as you'd like, possibly several paragraphs in length.
   
   Please provide a detailed explanation of what problem was solved, a
   good high-level description of how it was solved, and which parts of
   the code were affected (including function names as needed, for easier
   searching).  Including specific error messages, stack traces, and
   similar is also good.
   
   Patches claiming performance benefits should show actual numbers with
   a description of how they were measured.
   
   Wrap lines at 70 columns or fewer.
   
   Other useful commit message labels go here.
   
   Fixes: 1234567890ab ("LU-nnnn comp: old patch being fixed by this one")
   Signed-off-by: Random J Developer <[email protected]>
   Change-Id: Ica9ed1612eab0c4673dee088f8b441d806c64932

Adding the Change-Id field

Gerrit requires all changes to have the Change-Id: field, or it will be rejected. It should be added automatically by the .git/hooks/commit-msg script. See Commit Comments for a detailed description of the Change-Id: field.

Submitting Patches for Review, Testing, and Landing

All patches that land on the main release branches in the fs/lustre-release repository must conform to the Lustre_Coding_Guidelines, pass the standard Lustre regression tests. All patches should be associated with a Lustre Jira ticket, and contain a commit message the fully meets the Commit Comment Format Requirements. Bug fixes should include additional regression tests to ensure the problem is fixed, since the presence of the bug indicates that no test is covering this functionality, and the test will prevent the bug from being reintroduced in the future. Feature patches should include new regression tests to exercise the feature, and potentially performance or load tests as appropriate for the change. All changes submitted to the fs/lustre-release repository will be tested automatically with the Lustre regression tests in lustre/tests and a link to the test results (saved in Maloo) and a pass/fail review comment will be added to the Gerrit change. For additional tests run outside of autotest, the results can either be sent to Maloo manually, or test results can be posted into the Jira ticket associated with the patch.

Any patches that require updates to the Lustre manual will also need to submit documentation updates when the patch is ready for submission. See the Lustre_Manual_Changes page for more details.

Any additional feature testing that cannot be covered by the existing or added automated Lustre tests must also be documented with a clear, step-by-step test plan, and arrangements must be made with the Lustre test team to execute these plans.

A change request is created by pushing a patch to a special branch on the Gerrit repository. To create an change request for a patch in your local branch the local commit (or series of commits) needs to be pushed to the Gerrit review repository.

If there are a series of dependent changes being made to the code (e.g. code style fixes, renaming some functions, adding function parameters, moving code from one file to another, making the actual fix for a bug, making some additional fixes to other defects found during coding), these should all go into separate patches for Patch Inspections and testing. Having a series of smaller patches, each of which makes a single clearly understood change, speeds up inspection significantly and means those changes will land sooner. Ordering uncontroversial and easy-to-inspect changes first in a patch series ensures that they are only inspected a single time, and can land quickly. Ordering complex changes at the end of the patch series ensures that if changes are requested by the inspectors for these patches, the earlier ones do not need to be re-inspected and re-tested for each update. Following this patch submission model speeds up patch landing, and reduces the burden on the patch inspector, and test systems, and reduces the time that the patch submitter needs to spend waiting or rebasing in order to get their patches accepted.

Patch series should not be used for code that was written and then had a series of bug fixes applied to it after local testing. The later (local) bug fixes should be squashed into the original change before submission. Note that each patch in a series must build and pass testing before it can be landed, so compile warnings or test failures in the middle of a patch series are not allowed.

If you have a series of independent commits to be reviewed, each one should be in a separate local branch and pushed separately to Gerrit. This allows the patches to be reviewed, tested, and landed independently, and will avoid the overhead and delay of repeatedly reviewing, building, and testing patches that are only refreshed because of an earlier (unrelated) patch in a series being modified.

   $ git push ssh://[email protected]:29418/fs/lustre-release HEAD:refs/for/master

for the master branch of the fs/lustre-release repo, or:

   $ git push ssh://[email protected]:29418/fs/lustre-release HEAD:refs/for/b2_12

for the b2_12 branch of the fs/lustre-release repo, or:

   $ git push ssh://[email protected]:29418/tools/e2fsprogs HEAD:refs/for/master-lustre

for the master-lustre branch of the tools/e2fsprogs repo.

For convenience, you can add this to your ~/.ssh/config file:

   Host review
       Hostname review.whamcloud.com
       Port 29418
       User \{YourUserid\}
       IdentityFile ~/.ssh/my-key-id_rsa

Creating a review request for a change against master (assuming the remote alias has been added to ~/.ssh/config):

   $ git push ssh://review/fs/lustre-release HEAD:refs/for/master

Add the Gerrit server as a remote to your git repository:

   $ git remote add review ssh://review/fs/lustre-release

Automatically Building and Testing a Patch

When the patch has been pushed to the Gerrit fs/lustre-review repository, it will print a URL for that change set that should be added to the Jira ticket for tracking. This should now happen automatically.

All patches submitted to Gerrit will be built automatically by Jenkins for a number of different distro and kernel versions. Currently for the master branch this includes RHEL7 x86_64 client/server, Ubuntu x86_64/ARM clients, and SLES12 x86_64 client/server. The success/failure of these builds will be posted to the change in Gerrit as a link to the Jenkins build artifacts.

After a successful build on all of the configurations, one or more of the configurations will be regression tested automatically, and a link to the test results in Maloo will be posted to Gerrit. It is also possible to add special testing requests using the Test-Parameters: label when the patch is submitted. Normally, there are ten separate test sessions run for patches submitted to the master branch. The majority of the test sessions will be enforced, which means that they must pass in order to land the patch. In some cases test sessions may be marked optional and are not required to pass before landing (e.g. sessions for new distros/kernels, new features, etc.), but it is still desirable to check if they are failing due to issues introduced by the patch to avoid test regressions.

Automated regression testing for each patch should normally pass. In some cases it might fail for a variety of reasons, such as a bug in the patch, an intermittent test failure that is present in the existing code, problems with the testing system, etc. In all failure cases, the Maloo test failure(s) should be investigated as to the root cause. Once the cause of the test failure is identified in Maloo, the failed test result should either be linked (via [Associate bug]) to an existing LU ticket in Jira, or if necessary a new Jira ticket with details of the failure should be filed (via [Raise bug]), and a comment added to Gerrit with the JIRA LU ticket number. At this point the test could be resubmitted, if there are no other problems with the patch, or it can be refreshed if there are defects found in the patch and/or review comments that need to be addressed (per below).

Requesting Patch Review

In order to actually get a patch landed, you need to request at least two reviews in Gerrit for the patch. This is done by visiting the Gerrit web page for the change (at the URL returned when the commit was pushed, or it can be found from your home page after logging in). Enter the name or email address for the reviewer and click the [Add...] button in the top right corner.

If you are unsure of who should be the reviewer of your patch, you can use the get_maintainer.pl script to get a list of potential candidates. The commit hash shown in the example is optional, just to give a concrete example here) based on the MAINTAINERS file and recent commits to the modified files, otherwise it will examine the top patch on the branch:

   $ git show 8b364fbd6bd9e0088440e6d6837861a641b923a0 | ./contrib/scripts/get_maintainer.pl
   Patrick Farrell <[email protected]> (reviewer:Lustre Grant Space,commit_signer:4/6=67%,authored:1/6=17%)
   Bobijam Xu <[email protected]> (reviewer:Lustre Client IO stack,authored:1/6=17%,removed_lines:30/82=37%)
   Andreas Dilger <[email protected]> (commit_signer:3/6=50%,authored:1/6=17%,added_lines:25/65=38%,removed_lines:20/82=24%)
   Jinshan Xiong <[email protected]> (commit_signer:2/6=33%)
   Alexey Lyashkov <[email protected]> (commit_signer:2/6=33%)
   Li Dongyang <[email protected]> (commit_signer:2/6=33%,authored:2/6=33%,added_lines:28/65=43%,removed_lines:15/82=18%)
   Alexander Boyko <[email protected]> (authored:1/6=17%,added_lines:11/65=17%,removed_lines:16/82=20%)

The list is not always providing the best candidates, since it doesn't know the difference between someone making a cosmetic patch and the experts in the code, but at least it can provide a starting point. Usually it makes sense to include the top 2-3 people, in particular anyone marked reviewer for that code. The reported list of developers will change over time, as new commits are added to the affected files.


In conjunction with the two review requests, the patch has to successfully build on all supported architecture/distro combinations, and pass the automatic testing (as reported by Maloo). Once the patch has passed two reviews (Reviewed: +1 or Reviewed: +2 from reviewers that are not the change owner), built correctly (Verified: +1 from Jenkins), and has passed autotest (Verified: +1 from Maloo) the patch will automatically appear in the Gatekeeper's list of patches to land.

It is the responsibility of the patch submitter to request the reviewers to look at the patch, to check for build/test failures and annotate them correctly, and to refresh the patch after addressing review, build, or test issues. If this is not happening in a timely manner, one option is adding a comment into the patch to alert the reviewers that the patch needs attention.

Updating Patches After Review

Gerrit makes it easy to update a patch after review, and doing this allows reviewers to see differences between the patches so they only need to review the changes between the patches instead of having to review the entire patch again. Also, the original inline comments are maintained and moved to the new patches. The key to keeping updated review requests linked to the original patch is using the same Change-Id: field in the commit comment - this is what Gerrit uses to find the original patch to update.

A critical thing to point out is that you must submit a new version of the entire patch - not just an update to the patch.

The easiest way to update the most recent commit (which is often the one you want to update), is to use "git commit --amend -a". This will "add" any modifications in the current repository and merge them into the last commit. If there are no changes, or -a is not used, this will just allow you to edit the most recent commit message. This is useful if you don't have a Change-Id: line in your commit message (because you didn't install the commit-msg hook, see [#Formatting Git Commit Comments] above), but a Change-Id: was added automatically by Gerrit. You can copy the Change-Id: from the Gerrit web page for that change and paste it into the amended commit message. Typically, the updated patch should also be rebased to the tip of the current branch before pushing it again, to ensure that it does not conflict with other changes that may have been landed since the patch was first developed.

Another way of modifying a series of existing changes is to use "git rebase -i <parent-branch>". Interactive rebase will display a list of patches in an editor, and you can reorder the patches, "edit" the patch, "reword" the commit comments, and "squash" two patches into a single patch. See the help text in the commit message editor window for more information.

Once the change has been updated, push your branch to Gerrit again, and the original request will be updated with the new version of the patch.

Basing One Change on Another Unlanded Change

It is possible to base a new change, or rebase an existing change, on an uncommitted patch in Gerrit. This might be useful if both changes are impacting the same code, and one change is clearly dependent on another for some reason, or if they will cause conflicts when merged and a decision is made to land them in a specific order. It is desirable to break a patch into multiple functionally-separate commits for several reasons. If the patches are truly independent (i.e. no overlapping changes to the same files, no dependent functions, etc), then those patches should be submitted in separate branches, and this section does not apply.

If both patches are being developed by the same person, the easiest way to have a series of dependent changes is to commit them into separate patches order on the same branch. Then, when a change is made to any patch on that branch, all of the dependent changes will also be resubmitted to Gerrit so that they will be ready to land when the earlier patches are merged.

If updates or fixes need to be made to one of the patches, these updates should be merged into the original commit where the code was added, rather than being an additional patch at the end of the series. This can be done by running "git rebase -i <parent-branch>", then marking a particular patch for edit. That will cause the earlier patches in the series up to the to be applied, then stop for interactive editing/testing of that patch. Once the patch has been updated, run "git add -u" to include the new updates into this patch, and "git rebase --continue" to merge the updates into the existing patch and continue the rebase process.

In the case where changes need to be based on a patch from another developer, it is possible to check out the desired patch from Gerrit using one of the supplied Git URLs in the [Download v] section in the top right corner of the change page. Select the Checkout options, then copy the URL and paste it at the command prompt of a previously checked-out Lustre tree. For example to fetch patchset 16 from Change 1264, create a branch for it, and then create a new branch for your local changes based on that change, use:

   [lustre]$ git fetch http://review.whamcloud.com/p/fs/lustre-release refs/changes/64/1264/16 && git checkout FETCH_HEAD
   [lustre]$ git checkout -b b_1264
   [lustre]$ git checkout -b b_1264_my_changes
   {edit local tree to make changes as usual}
   [lustre]$ git commit -a

Any changes in the b_1264_my_changes will be based on top of those of b_1264. When b_1264_my_changes is pushed to Gerrit, it will have a dependency on change 1264, so it will not be able to land until change 1264 itself is landed. It is typically not desirable to locally rebase the b_1264 branch to a new version of master or modify it, or it will cause the other developer's patch to be updated in Gerrit, and lose its existing review and test results. However, in some cases this is desirable, and Gerrit allows a user other than the original author to push an updated version of the patch (using the same Change-Id: label) in case there is a problem with the original patch (e.g. no longer applies, has a bug, etc).

If you already have the changes in a local branch (e.g. b_my_changes) and want to rebase that branch on top of another uncommitted patch from Gerrit, the process is similar:

   [lustre]$ git fetch http://review.whamcloud.com/p/fs/lustre-release refs/changes/64/1264/16 && git checkout FETCH_HEAD
   [lustre]$ git checkout -b b_1264
   [lustre]$ git checkout b_my_changes
   [lustre]$ git rebase --onto b_1264

That will rebase the patch(es) in the current branch onto the other patch (or branch) checked out from Gerrit.

Pushing a Git Tag

This is normally done by the branch maintainer, but is recorded here for future reference.

Switch to the branch you want to create a branch in (normally master or a release branch like b2_12).

Create the tag with:

   $ git tag -a TAG_NAME

then push it upstream with

   $ git push TAG_NAME

Note, this requires certain privileges on the server. If review is a secondary server for your repository, use:

   $ git push review TAG_NAME

Searching on Gerrit

This is covered on the page: Useful Gerrit Searches