Setting up Gerrit

All projects under the Qt Open Governance umbrella are hosted on our Gerrit Instance. There is an official mirror and browser of these repositories.

In order to be able to propose changes to those projects, you have to first setup your Gerrit account and get Qt's sourcecode, following the steps below:

Set up a Gerrit account
Tweak your SSH config as instructed here
Use the recommended Git settings, defined here
Get the source code of the projects you want to contribute to

Moreover, if you did not use the init-repository scripts to get the source code, you will have to manually:

Set up the git commit hooks .
Set up a Gerrit git remote.

Once all the steps above have been completed, you're ready to submit your patch to Qt!

How to get started - Gerrit registration

Create a Qt account, if you don't have one yet.
- Note: Use an all-lowercase user name. Otherwise, Gerrit will lowercase it for you, and as it is case sensitive, you will have to use mismatched login names.
Log into https://codereview.qt-project.org with your Qt account.
Go to "Settings" -> "Contact Information", set your real name and register your email address, if it hasn't been automatically registered.
- You will receive a confirmation email; click on the link inside to finalize your registration.
  - If you use Outlook, manually copy the link including any trailing equal signs into the browser.
- Note: The email address you use to contribute to the Qt Project will be publicly visible in the Git history. Use an alias + a custom e-mail address if you want to stay anonymous (this is discouraged)
Review and agree to the Qt Project's contribution license agreement (CLA) in Gerrit. You need to do this only once, unless the license changes.
- If your company has a corporate contribution agreement, ask the admin of your company's Gerrit user group to add your account to this group.
- More details about the CLA can be found here.
Go to "Settings"-> "SSH Public Keys" and upload your public SSH Key
If you are behind a firewall that blocks SSH access:
1. Go to "Settings" -> "HTTP Password"
2. Click "Generate Password"
3. Add the following line to your ~/.netrc (Windows: %USERPROFILE%\_netrc):
```
machine codereview.qt-project.org login <Gerrit username> password <Generated password>
```

Local Setup

Proper configuration of SSH for your Gerrit account is necessary for the URLs in the next steps.

Note: On windows, the ~/ shorthand used below can be equated with C:\Users\%USERNAME%\. Make replacements in the example as necessary.

Edit ~/.ssh/config with host information for Gerrit, as shown below. Do not copy comments marked by #, as they may not be ignored by your SSH client.

Host codereview.qt-project.org
    Port 29418
    # Use your Gerrit username, not email or your username on your own machine.
    # You can view this from Settings in gerrit when logged in.
    User yourgerritusername
    PreferredAuthentications publickey
    IdentityFile ~/.ssh/id_rsa

Next, you will need to ensure that you have an SSH key pair, and make it known to Gerrit.

If you have no key pair on this machine yet, generate one now. On the command line, invoke:
ssh-keygen -t rsa -b 4096 -C unique-identifier-for-this-machine -f ~/.ssh/id_rsa
Note: SSH keys are intended to be unique to each machine. New keys must be created for each additional machine logging in to Gerrit with SSH.
Open the ~/.ssh/id_rsa.pub file with a text editor and copy its entire contents into the clipboard.
Log into https://codereview.qt-project.org and navigate to Settings (the gear symbol on the top right) → SSH Keys
Paste the clipboard into the New SSH key entry, and hit the ADD NEW SSH KEY button.

You can verify that the connection works by running:
ssh codereview.qt-project.org

If the connection is functional, you should see a welcome message. End the connection by pressing Ctrl-C.

Configuring Git

We are developing in a heterogeneous environment with both Unix and Windows machines. Therefore it is imperative to have all files in the repository in the canonical LF-only format. Therefore, Windows users must run

git config --global core.autocrlf true

to automatically get CRLF line endings which are suitable for the native tools, and Unix users should use

git config --global core.autocrlf input

(this is a safety measure for the case where files with CRLF line endings get into the file system- this can happen when archives are unpacked, attachments saved, etc.).

To be able to create commits which can be pushed to the server, you need to set up your committer information correctly:

git config --global user.name "Your Name"
git config --global user.email "me@example.com"

Please do not use nicknames or pseudonyms instead of the real name unless you have really good reasons. Gerrit will not accept your commits unless the committer information matches the email address(es) you registered.

To facilitate following the style guide for commit messages, it is recommended to install the Qt commit message template:

git config --global commit.template <path to qt5.git or qt.git>/.commit-template

Sometimes it is necessary to resolve the same conflicts multiple times. Git has the ability to record and replay conflict resolutions automatically, but - surprise surprise - it is not enabled by default. To fix it, run:

git config --global rerere.enabled true
git config --global rerere.autoupdate true # this saves you the git add, but you should verify the result with git diff --staged

git pull will show a nice diffstat, so you get an overview of the changes from upstream. git pull --rebase does not do that by default. But you want it:

git config --global rebase.stat true

To get nicely colored patches (from git diff, git log -p, git show, etc.), use this:

git config --global color.ui auto
git config --global core.pager "less -FRSX"

Git supports aliases which you can use to save yourself some typing. For example, these (any similarity with subversion command aliases is purely accidental ;)):

git config --global alias.di diff
git config --global alias.ci commit
git config --global alias.co checkout
git config --global alias.ann blame
git config --global alias.st status

Getting the source code

Cloning Qt5

You should clone from the official mirror and track changes from there in order to keep the load on Gerrit down.

This guide will show you how to get and build the source code.

After getting the source code, if you did not use the init-repository script to clone the source code as described in the guide, or you want to manually clone only a submodule, make sure you also manually set up the git commit hooks and set up a git remote that point to Qt's gerrit instance.

Cloning Qt Creator

git clone git://code.qt.io/qt-creator/qt-creator.git

Setup the gerrit remote

git remote add gerrit ssh://codereview.qt-project.org/qt-creator/qt-creator

If you are behind a SSH-blocking firewall, use the https protocol:

git remote add gerrit https://codereview.qt-project.org/a/qt-creator/qt-creator

Setting up git hooks

NOTE: This is only needed if you did NOT use the init-repository script to get the source code, that automatically configures the git hooks for you.

To set up the git hooks, install the hook generating Commit-Id files into your top level project directory, as well as all sub-repositories (e.g. qtbase.git) either through (bash)

gitdir=$(git rev-parse --git-dir); scp -P 29418 codereview.qt-project.org:hooks/commit-msg ${gitdir}/hooks/

or for Powershell, using utilities provided by puTTY:

$gitdir=$(git rev-parse --git-dir); pscp -p -P 29418 <user>@codereview.qt-project.org:hooks/commit-msg $gitdir/hooks/

or by downloading the file via browser: commit-msg and putting it into the .git/hooks directory (make sure it is executable).

It is recommended to install the git_post_commit_hook from the qtrepotools repository. This gives you the checks of the Sanity Bot locally. To do this, save the script

#! /bin/sh
exec "<path to git clone>/qtrepotools/git-hooks/git_post_commit_hook" "$@"

into each <path to git clone>/.git/hooks/post-commit

NOTE: Starting with git 1.7.8, if <module name>/.git contains gitdir: ../.git/modules/<module name>, you need to put the submodule hooks in .git/modules/<module name>/hooks instead of <module name>/.git/hooks.