Sending your first change for review in Gerrit

Gerrit workflow is entirely different from the review model used by GitHub (and Forgejo, GitLab, BitBucket) so new users must expect some learning curve.

The guide below explains what you need to do but it does not dive deep into why you do that and how Gerrit interprets your actions under the hood. Please consult Gerrit documentation or third-party for more information.

Initial configuration

• Log into Gerrit
• Add your SSH public key
• Setup Gerrit as a remote in your local git repository:

• Clone repository to a new local directory and setup commit hook automatically

  (command line is provided on repository page)

  

• Or add Gerrit remote to existing checkout: \ git remote add review ssh://$GERRIT_USERNAME@review.frostfs.info:2222/TrueCloudLab/$REPOSITORY, and save commit-msg hook script to .git/hooks/commit-msg

• Some teams may choose to add the steps above to their Makefile

Preparing and sending a change

• Make changes to the source code
• Prepare git commits. Keep in mind that each commit will be reviewed individually:
• Modify your commits (amend/squash) to represent a single reviewable unit of work
• Add a good commit message. This will be the only supporting text you will send along with your code to reviewers, make sure it explains the purpose of proposed change and answers the questions that reviewers may want to ask. There is no separate PR message in Gerrit, so make your commit message count.
• Make sure that repository remains buildable/testable after each commit. CI jobs will be triggered for every individual commit and will notify you if you miss anything.
• Push your commit for review. Gerrit uses a virtual branch for incoming reviews: git push review HEAD:refs/for/master will create a new code review for commits from your local HEAD (to be later merged into master).

If you push more than one commit (a branch with multiple commits), a separate review thread will be started for each commit and URLs of all your changes will be printed to your terminal. - Gerrit supports passing extra parameters along with git push. Some teams use this to hardcode a default list of reviewers to their Makefile

Modifying your submission based on review feedback

It is likely that reviewers will want you to make some modifications to your change before it's submitted. You should make these changes in scope of the corresponding commit:

• If you have submitted a single commit for review the easiest way to modify it would be with git commit --amend
• If you have submitted a branch with multiple commits you may:
• Checkout a specific commit you want to modify and use git commit --amend
• Or add modification commits on top of your submitted branch and then do an interactive rebase: git rebase -i to squash your changes into their corresponding commits
• Minor modifications may also be made directly from web interface. Be careful not to overwrite such changes with subsequent local edits. You may need to fetch patchsets from Gerrit: use 'Download patch' menu to view relevant links and command lines.

After you have modified your changes you should push them with the same command as you've used previously: git push review HEAD:refs/for/master. refs/for/master is not a real branch, Gerrit will parse Change-Id from your commits and will create new patchsets for the corresponding review thread(s).

Merging a change after review

Review process completes when your change receives enough positive votes (and loses enough negative votes) to pass Submit Requirements configured for the target repository. You may view current change status in web interface (hovering over votes will show extra details):

After your change becomes 'Ready to submit' you (or any other Gerrit user) may merge it into target branch by clicking the Submit button in web UI. Traditionally Gerrit changes are expected to be merged by their author (the person who has the most context in their head) but some teams may have other processes.

Personal repository forks

Gerrit does not follow GitHub model of personal forks and pull requests to origin. All changes you push to Gerrit are expected to be ready (or almost ready) for review.

If you only want to save a modified copy of a codebase somewhere you may continue using personal forks in Forgejo - it is not going anywhere anytime soon. Work in progress backups, exploratory experiments, soft forks for personal use can and should live exclusively in Forgejo - until and unless you wish to initiate a code review process for merging into main repository.

Personal repository forks in Gerrit currently are not supported and are not planned to be supported.