= Useful tips and hints about using Gerrit =

For using https://gerrit.openvpn.net/ to submit and/or review OpenVPN 2.x patches. See [DeveloperDocumentation#PatchsubmissionviaGerrit 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 [https://community.openvpn.net/register here].

== Documentation ==

Gerrit comes with extensive documentation. Before using it you should make yourself familiar at least with the basics in the [https://gerrit.openvpn.net/Documentation/intro-user.html 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 [https://gerrit.openvpn.net/Documentation/user-search.html 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.