- 1 Setting Yourself Up For Gerrit
- 2 Sending a Patch to Gerrit
- 3 More on Gerrit
- 4 Further reading
This is the entry page on the code review tool gerrit.libreoffice.org and how to use it in LibreOffice.
Setting Yourself Up For Gerrit
Before you start: Troubleshooting help
The instructions below should be easy and quick to follow. However, if you get stuck somewhere, here is how you get help:
Register in Gerrit for first time
In order to create a new account in Gerrit, launch gerrit and click on the “Register” link at the top right of the page, pick your favorite OpenID (List of OpenID providers) or OAuth2 provider and use it to log in.
Currently two OAuth2 providers are supported (pending OAuth2 plugin activation):
Switch accounts in Gerrit (Link another identity)
Different OpenID or OAuth2 account can be used (linked) to the same Gerrit user accounts.
To link new OpenID or OAuth2 account to the existing Gerrit account:
- login with your existing account into Gerrit
- navigate to https://gerrit.libreoffice.org/#/settings/web-identities ▸ ▸ or go directly to
- Push "Link another identity" button
- Select alternative identity
Setting yourself up for gerrit - the easy way
If you have a checkout of libreoffice/core already, you can just run
./logerrit setup, which will try to automatically setup keys and configure ssh for you, and if it can't it will guide you through these steps: if necessary, just follow the steps.
The program will tell you to go to https://gerrit.libreoffice.org, click Register and remember your username. The program will also generate a public SSH key, print it and save it to
/home/[username]/.ssh/id_rsa.pub. This key will begin with 'ssh-rsa'. You must enter this key during the registration process on the website (or add it later in SSH Public Keys under Settings in order for gerrit to work.
./logerrit test fails and
ssh -vvv logerrit informs you about
~/.ssh/config having bad permissions, run
chmod 600 config in
The alternative is fiddling with the manual approach, details of which can be found at Development/gerrit/setup.
Sending a Patch to Gerrit
Add yourself to the contributor list
If this is the first time you are contributing a patch to the LibreOffice project, please add yourself to the developer and contributor list (following the instructions there) and state the license of your contributions.
Submitting patches for review
Then create and push your change to gerrit for review (official gerrit documentation is here):
git checkout -b <a_local_branch_name_of_your_choice> # Do your code changes, make sure it will build git add file [file ...] # all the new files _and_ changed files git commit ./logerrit submit master
Note: for the `logerrit` command to work, make sure you have set yourself up o for gerrit. Instructions can be found here.
Note: the git add + git commit step can be done using 'git gui', please remember that the commit subject line should not be longer than 65 characters and the commit message lines, if any, should not be longer than 70 character.
Note: for submissions to master, it is useful to (re)base the changes on a recent version of master, so that CI builds on jenkins can benefit as much as possible from ccache.
Note: LibreOffice uses clang-format to check the patches for conformance to established rules. We use a specific version of clang-format (to avoid inconsistencies that exist between different versions of it, even between minor releases). If there's no clang-format preinstalled on system, a warning will be issued at the time of git commit, with instructions on how to install the required binaries. If you have some version preinstalled, you might not see warnings (but have inconsistent results when buildbots would fail telling you to change formatting the other way), or the preinstalled version might not work (e.g., complaining about command line options). The version used by LibreOffice may be found at https://dev-www.libreoffice.org/bin/.
Only the last line is special and will push all patches in the named local branch to the review queue for the master branch (Adjust accordingly, if you want to submit a patch to one of the release branches or other branches). As a casual contributor your patch needs to have the same email address as your gerrit account has or you will not be allowed to push.
If the push succeeds, git will report where your commit is waiting for review. The url will look something like https://gerrit.libreoffice.org/#/c/229/.
It is a good idea to keep your local branch around while your patch is under review, that will allow to possibly easily push a new version of the patch. In the mean time you can
git checkout master
To return to the master branch... and you can start working on another patch using again the procedure above (create local branch, code, commit, push to gerrit).
More on patch submission
As an alternative to the above, you can consider using "git review", as explained at Development/GitReview.
At Development/gerrit/SubmitPatch you will find a discussion of topics like:
- submitting a new version
- submitting patches as drafts
At Development/Submodules you will find a discussion of submitting patches to submodules such as
- helpcontent2 (for help files)
More on Gerrit
- see Development/gerrit/PatchReview on how to do review of patches on gerrit
- Split Patch after it was uploaded to gerrit
- Got a question? Consult the gerrit FAQ first or ask on the development mailing list. You can also take a look at the the official gerrit documentation.