Useful tips and hints about using Gerrit

For using ​https://gerrit.openvpn.net/ to submit and/or review OpenVPN 2.x patches. See Developer Documentation for how Gerrit is integrated in the Patch Submission workflow.

Account Creation

Our Gerrit instances uses the same account database as this Wiki. Please create your account ​here.

Documentation

Gerrit comes with extensive documentation. Before using it you should make yourself familiar at least with the basics in the ​User Guide. The rest of this page will assume that you have read the parts relevant to you and not generally repeat information covered there.

Identity Settings

Make sure you review the user settings for your account. At the very least make sure that

• Display Name field is correct
• you add all the email addresses which might appear in Author fields in Git commit
• you select your correct preferred email address

We might use this information to construct Acked-by statements when you review commits.

Search / Menu settings

Gerrit has a lot of options for creating search queries. You can find them in the ​Documentation. If you need a specific query regularly, you can add your own menu entry for yourself in your User Settings.

Example query: #/q/is:submittable+status:open+-inhashtag:mailsubmitted lists all the changes that are submittable, not merged, and do not have the hashtag mailsubmitted. We use this to look for changes that ready to be sent to the mailing list.

Submission to the mailing list

While we use Gerrit for code review, we currently do not merge commits directly in Gerrit. Instead we still use the openvpn-devel mailing list as the collection point for all patches. So if a commit has been reviewed in Gerrit and is ready for merge, it still needs to be sent as a patch to the mailing list. To simplify this task, a script is provided as ./dev-tools/gerrit-send-mail.py that anyone can use to create an email to send to the list.

The script does only prepare the email, it does not actually send it. But it gives you a git send-email command you can use to send it that will make the mail appear as a part of the thread that contains the Gerrit notifications about this commit. The script itself only uses publicly available APIs and does not need any credentials right now.

Example usage:

$ ./dev-tools/gerrit-send-mail.py 374
https://gerrit.openvpn.net/changes/374?o=CURRENT_REVISION&o=LABELS&o=DETAILED_ACCOUNTS
Acked-by: Frank Lichtenheld <frank@lichtenheld.com>
https://gerrit.openvpn.net/changes/374/revisions/1/patch?download
send with:
git send-email --in-reply-to gerrit.1697649588000.I3ca6965799b23d542ababc3e38880317cb46a3ac@gerrit.openvpn.net gerrit-374-1.patch
$ git send-email --in-reply-to gerrit.1697649588000.I3ca6965799b23d542ababc3e38880317cb46a3ac@gerrit.openvpn.net gerrit-374-1.patch

Note that this assumes that the required configuration for git send-email is present in one of the standard git configuration files (.git/config, ~/.gitconfig, etc).

Anyone can use the script to send the mail to the list, as long as they are subscribed to the list. Obviously this should only be used for commits that are ready for merge. Commit authors are encouraged to make this call and send their own patches to the list.

If you have submitted a patch to the list please set the mailsubmitted hashtag for that change to document this fact. This helps the maintainers to look for missing submissions.

Gerrit notification mails

You can configure which Gerrit notification mails you want to receive in your User Settings.

Please note that all notifications are also sent to the openvpn-devel mailing list. However, the mailing list has a duplication filter. If it sees that the email was also addressed to you personally, it will not send you an additional copy via the list! This sometimes causes confusion with people thinking the mail was not sent to the list at all.