Note: this page is partly redundant with Qt Contribution Guidelines, which gives a better introduction.

Code Reviews

Participating in the Qt project by contributing and reviewing

This Wiki provides information on how to contribute and review code. It also provides directions to the information on Gerrit and Git used for developing Qt.

Overview of the technical landscape

The servers, database, and tools related to the Qt Open Governance code contribution process as well as their interactions are illustrated in the adjacent picture. The process has been designed to provide increased transparency and quick pass-through for code contributions, and its core is the easy-to-use code review tool, Gerrit. The tool is available for everybody, and besides using it for its main purpose of contributors and feedback gathering, it can be utilized for studying the code of the other contributors.

Here’s an overview diagram of the process:

In order to gain access and log in to Gerrit, a contributor needs to have an existing JIRA account. A new account can be obtained from

Gerrit tool is used in the Qt Project for approval of changes and both automated quality checks and human reviews. It is hosted under the domain. Contributions are sent as patches to Gerrit with the Git push command, with target ref as refs/for/<branch name>. There will be no direct pushing into a branch. Repository can be accessed with SSH on port 29418.

Continuous Integration (CI) system is used for building and testing. CI fetches reviewed changes from Gerrit, runs build & test for the changes and transfers the changes passed further to the public tip. Staging branches are stored in the Git repository of Gerrit.

In addition to Gerrit’s Git repository, the repository is pushed to Gitorious repository on That repository is read-only.

Using Git

Using Gerrit


Checklist for contributing

In order to contribute person needs to have:

  • JIRA account: can be created from
  • Register to Gerrit using e-mail
  • Accept the Contributor License Agreement
    • Individual contributor does that in Gerrit (Settings -> Agreements -> New Contributor Agreement)
    • Corporate contributor needs to fill in CLA for corporate contributor
  • If code is contributed user needs to clone the source code (see: Get the source [])

Troubleshooting Table

Symptom Cause Solution
When I click the email verification link in Outlook, Gerrit told “Invalid token”Outlook doesn’t activate the link correctly. Specifically, the last two “h2. “ are omitted when clicking on the linkCopy and paste the link into a web browser, instead of clicking on it
“git push” fails with: “error: failed to push some refs to …”Many possible causes. Generic error message.Please read the rest of the output of “git push” to determine the root cause (especially lines beginning with “remote:”).
“git push” fails with: “ERROR: missing Change-Id in commit message”.You tried to push a commit whose commit message didn’t contain a “Change-Id” line. This may be:.
.commit is newTo prevent the problem occurring for new commits, install the commit message hook according to the instructions under Setting up Gerrit Local Setup. Then use git commit —amend to fix up the current commit (just exit the commit message editor without changing anything).
.a commit you have cherry-picked from outside of GerritUse one of these tools to add a Change-Id (roughly listed in order of expertise required): git commit —amend, git-edit-commit (from devtools/mainline.git), git rebase —interactive
“git push” fails with “ERROR: you are not allowed to upload merges”You tried to push a merge commit for review, which is not allowed by default.Contact one of the administrators listed in the Gerrit Registration section and ask for permission to do merges. The primary reason for this is to reduce the risk of accidental pushing of merges (e.g. by users who use Git in a CVS-like manner, without learning about effective usage of merges and rebases).
I can’t give +2 to anything, or submit or stage anythingYou’re not in the “Approvers” group.Apply for approver status according to the Qt Governance Model. If your status was confirmed but not executed yet, contact one of the administrators listed in the Gerrit Registration section to add you to the “Approvers” group.
“Qt Sanity Bot” gave a -1 to my change!An automated sanity check bot found out that change contains some problem.First, really try to understand the problem. Don’t proceed until you understand the output of the bot. Then make an informed decision to either fix it (e.g. by amending your change with the fix and pushing it again), or ignore it. The sanity bot’s output is advisory in cases where it is determined heuristically.
“Qt Sanity Bot” gave a -2 to my change!An automated sanity check bot found out that change contains some serious problem.First, really try to understand the problem. If you are convinced that the bot made a mistake, contact a member of the Administrators group on Gerrit.
“Qt Continuous Integration System” said my change failed, but I’m sure my change is OK!The test procedure for your change failed. It could be:.
.a regression caused by someone else’s change which was tested at the same timeSimply stage your change again.
.a regression caused by a change in some dependency of the module you’re working on (e.g. a qtbase bug breaking qtdeclarative)Fix the bug in the dependency, or ensure someone else fixes it, before re-staging your change.
.an unstable failure due to bugs in the code (e.g. an autotest which fails ~50% of the time, seemingly at random)Fix the instability in a separate commit before re-staging your change, or consult QA for advice.
.bugs or infrastructure problems in the CI system.Consult QA for advice.
.a regression genuinely caused by your changeReconsider if you should really be “sure” that your change is OK. For a project the size of Qt, it is common for changes in one part of the code to affect other parts of the code in unexpected ways.

A Real World Troubleshooting Example

This is a lightly edited log of troubleshooting an attempt to push a commit to gerrit for Qt 4.8.

  1. [20:16] <curius> git gives me this "error: failed to push some
  2. refs to 'ssh://'"
  3. [20:16] <richmoore1> curius: login to gerrit
  4. [20:16] <richmoore1> curius: click settings at the top right
  5. [20:17] <richmoore1> curius: click Agreements on the left at the bottom of the list
  6. [20:17] <curius> verified
  7. [20:17] <richmoore1> ok, good
  8. [20:17] <richmoore1> now click ssh public keys
  9. [20:18] <richmoore1> do you see your key?
  10. [20:19] <curius> yes
  11. [20:19] <richmoore1> okay
  12. [20:20] <richmoore1> so we know that in theory you can push but there's likely some problem with /what/
  13. your trying to push, or where it's going to
  14. [20:20] <peppe> curius: Change-Id installed?
  15. [20:21] <curius> Change-Id? don't know what that is :)
  16. [20:21] <curius> the git/hook thing?
  17. [20:21] <richmoore1> yes, it should be in your commit message
  18. [20:21] <richmoore1> do you see a line like Change-Id: Iffbdf8f5ec366d9f41debcf8301340b5ff2207bb
  19. [20:21] <qt_gerrit>,Iffbdf8f5ec366d9f41debcf8301340b5ff2207bb,n,z
  20. [20:22] <curius> oh.. ok, there is a change-id, yes
  21. [20:23] <curius> Change-Id: Ibc7546c522506b2c4e7a729a8de319aea788b662
  22. [20:23] <qt_gerrit>,Ibc7546c522506b2c4e7a729a8de319aea788b662,n,z
  23. [20:24] <richmoore1> okay, so we know you have the git hooks working
  24. [20:25] <richmoore1> curius: the problem is probably that you've fallen behind the current tree
  25. [20:25] <richmoore1> curius: do a git pull to get yourself up to date
  26. [20:26] <richmoore1> curius: you may need to tweak your change to make it work after this
  27. [20:28] <curius> git pull ssh://
  28. [20:28] <curius> this says 'Already up-to-date'
  29. [20:29] <richmoore1> okay, what else did it say when you tried to push?
  30. [20:30] <curius>

The contents of the pastebin were as follows:

  1. Counting objects: 7, done.
  2. Delta compression using up to 4 threads.
  3. Compressing objects: 100% (4/4), done.
  4. Writing objects: 100% (4/4), 555 bytes, done.
  5. Total 4 (delta 3), reused 0 (delta 0)
  6. remote: Resolving deltas:   0% (0/3)
  7. To ssh://
  8.  ! [remote rejected] HEAD -> refs/for/master (branch master not found)
  9. error: failed to push some refs to 'ssh://
  10. :29418/qt/qt'

  1. [20:31] <richmoore1> aha, see line 8?
  2. [20:31] <curius> yes? branch master not found ?
  3. [20:32] <richmoore1> yes, that's the problem. iirc you're trying to push to qt 4.8 yes?
  4. [20:32] <curius> yes, 4.8 master
  5. [20:32] <richmoore1> okay, so we need to find out what the branch is
  6. [20:33] <richmoore1> answer 4.8
  7. [20:33] <curius> on branch 4.8
  8. [20:33] <curius> yes
  9. [20:33] <curius> ohh.. refs/for/4.8 ??
  10. [20:33] <richmoore1> yep
  11. [20:34] <curius> thank you :D
  12. [20:34] <curius>,15262
  13. [20:34] <richmoore1> bingo :-)
  14. [20:35] <curius> who's going to review it? it's very very trivial fix?
  15. [20:35] <richmoore1> it's qmake. so add ossi
  16. [20:36] <richmoore1> or i can add him for you if you want
  17. [20:36] <curius> yes, please :)
  18. [20:36] <curius> add him
  19. [20:36] <richmoore1> done
  20. [20:37] <curius> ahhh, nice :) ... and now i wait for ossi to see it, right?
  21. [20:37] <richmoore1> yep
  22. [20:37] <richmoore1> you'll get mailed when there's comments etc.
  23. [20:38] <richmoore1> and you can push again using the same commit id (eg. via updating
  24. your commit with git commit -amend to address any issues found during the review)