Setting-up-Gerrit: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
Line 1: Line 1:
[[C@egory:Developing_Qt::Instructions]]
[[Category:Developing_Qt::Instructions]]


= Setting Up Gerrit =
= Setting Up Gerrit =


[toc align_right="yes" depth="3"]All projects under the Qt Open Governance umbrella are hosted @ "codereview.qt.io":http://codereview.qt.io. These repositories are mirrored on "Gitorious":http://qt.gitorious.org.
[toc align_right="yes" depth="3"]All projects under the Qt Open Governance umbrella are hosted at "codereview.qt.io":http://codereview.qt.io. These repositories are mirrored on "Gitorious":http://qt.gitorious.org.


== How to get started - Gerrit registr@ion ==
== How to get started - Gerrit registration ==


# Cre@e an account in the "Qt bug tracker":https://bugreports.qt.io/ (also known as JIRA)
# Create an account in the "Qt bug tracker":https://bugreports.qt.io/ (also known as JIRA)
# Go to https://codereview.qt.io and log in with your Qt bug tracker credentials
# Go to https://codereview.qt.io and log in with your Qt bug tracker credentials
#* '''Note''': Gerrit usernames are case-sensitive, but JIRA usernames are not. If you @tempt to log into Gerrit with different capitaliz@ions, you will end up with multiple accounts.
#* '''Note''': Gerrit usernames are case-sensitive, but JIRA usernames are not. If you attempt to log into Gerrit with different capitalizations, you will end up with multiple accounts.
# Go to the Settings page: https://codereview.qt.io/settings/
# Go to the Settings page: https://codereview.qt.io/settings/
# Go to "Settings" -> "Contact Inform@ion" and register your email address. You will receive a confirm@ion email; click on the link inside to finalize your registr@ion.
# Go to "Settings" -> "Contact Information" and register your email address. You will receive a confirmation email; click on the link inside to finalize your registration.
'''''' '''Note''': Your username and e-mail address will be visible to the public. Use an alias + a custom e-mail address if you want to stay anonymous (this is discouraged)
'''''' '''Note''': Your username and e-mail address will be visible to the public. Use an alias + a custom e-mail address if you want to stay anonymous (this is discouraged)
# Go to "Settings"-> "SSH Public Keys" and upload your "public SSH Key":https://help.github.com/articles/gener@ing-ssh-keys , configure username (under contact inform@ion), upload public "SSH key":https://help.github.com/articles/gener@ing-ssh-keys
# Go to "Settings"-> "SSH Public Keys" and upload your "public SSH Key":https://help.github.com/articles/generating-ssh-keys , configure username (under contact information), upload public "SSH key":https://help.github.com/articles/generating-ssh-keys
# If you are behind a firewall th@ blocks SSH access:
# If you are behind a firewall that blocks SSH access:
## Go to "Settings" -> "HTTP Password"
## Go to "Settings" -> "HTTP Password"
## Click "Gener@e Password"
## Click "Generate Password"
## Add the following line to your <code>~/.netrc</code> (Windows: <code>​%USERPROFILE%netrc</code>):
## Add the following line to your <code>~/.netrc</code> (Windows: <code>​%USERPROFILE%netrc</code>):
<code>
<code>
machine codereview.qt.io login <Gerrit username> password <Gener@ed password>
machine codereview.qt.io login <Gerrit username> password <Generated password>
</code>
</code>


Line 35: Line 35:
'''NOTE:''' The following steps need to be applied to every clone:
'''NOTE:''' The following steps need to be applied to every clone:


Install the hook gener@ing Commit-Id files into your top level project directory, as well as all sub-repositories (e.g. qtbase.git) either through
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


<code>
<code>
Line 46: Line 46:
<code>
<code>
#! /bin/sh
#! /bin/sh
exec "<p@h to git clone>/qtrepotools/git-hooks/git_post_commit_hook" "(@)quot;
exec "<path to git clone>/qtrepotools/git-hooks/git_post_commit_hook" "@quot;
</code>
</code>
into each <p@h to git clone>it\hooks\post-commit
into each <path to git clone>it\hooks\post-commit


'''NOTE:''' Starting with git 1.7.8, if <code><module name>/.git</code> contains <code>gitdir: ../.git/modules/<module name></code>, you need to put the submodule hooks in <code>.git/modules/<module name>/hooks</code> instead of <code><module name>/.git/hooks</code>.
'''NOTE:''' Starting with git 1.7.8, if <code><module name>/.git</code> contains <code>gitdir: ../.git/modules/<module name></code>, you need to put the submodule hooks in <code>.git/modules/<module name>/hooks</code> instead of <code><module name>/.git/hooks</code>.
Line 54: Line 54:
h3. Configuring Git  
h3. Configuring Git  


We are developing in a heterogeneous environment with both Unix and Windows machines. Therefore it is imper@ive to have all files in the repository in the canonical LF-only form@. Therefore, Windows users '''must''' run
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


<code>
<code>
Line 60: Line 60:
</code>
</code>


to autom@ically get CRLF line endings which are suitable for the n@ive tools, and Unix users ''should'' use
to automatically get CRLF line endings which are suitable for the native tools, and Unix users ''should'' use


<code>
<code>
Line 66: Line 66:
</code>
</code>


(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, @tachments saved, etc.).
(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 cre@e commits which can be pushed to the server, you need to set up your committer inform@ion correctly:
To be able to create commits which can be pushed to the server, you need to set up your committer information correctly:


<code>
<code>
  $ git config —global user.name "Your Name"
  $ git config —global user.name "Your Name"
  $ git config —global user.email "m(@)xample.com"
  $ git config —global user.email "m@xample.com"
</code>
</code>


Please do not use nicknames or pseudonyms instead of the real name unless you have really good reasons.
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 inform@ion m@ches the email address(es) you registered.
Gerrit will not accept your commits unless the committer information matches the email address(es) you registered.


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


<code>
<code>
  $ git config —global commit.templ@e <p@h to qt5.git or qt.git>/.commit-templ@e
  $ git config —global commit.template <path to qt5.git or qt.git>/.commit-template
</code>
</code>


A common mistake is forgetting to add new files to a commit. Therefore it is recommended to set up git to always show them in <code>git st@</code> and <code>git commit</code>, even if this is somewh@ slower (especially on Windows):
A common mistake is forgetting to add new files to a commit. Therefore it is recommended to set up git to always show them in <code>git stat</code> and <code>git commit</code>, even if this is somewhat slower (especially on Windows):


<code>
<code>
  $ git config —global st@us.showuntrackedfiles all
  $ git config —global status.showuntrackedfiles all
</code>
</code>


Git has a somewh@ stupid default th@ <code>git push</code> will push ''all'' branches to the upstream repository, which is almost never wh@ you want. To fix this, use:
Git has a somewhat stupid default that <code>git push</code> will push ''all'' branches to the upstream repository, which is almost never what you want. To fix this, use:


<code>
<code>
Line 96: Line 96:
</code>
</code>


This is not relevant for mainline branches under Gerrit control, as all pushing happens with refs anyway, but it may be important for your priv@e clones.
This is not relevant for mainline branches under Gerrit control, as all pushing happens with refs anyway, but it may be important for your private clones.


Sometimes it is necessary to resolve the same conflicts multiple times. Git has the ability to record and replay conflict resolutions autom@ically, but - surprise surprise - it is not enabled by default. To fix it, run:
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:


<code>
<code>
  $ git config —global rerere.enabled true
  $ git config —global rerere.enabled true
  $ git config —global rerere.autoupd@e true # this saves you the git add, but you should verify the result with git diff —staged
  $ git config —global rerere.autoupdate true # this saves you the git add, but you should verify the result with git diff —staged
</code>
</code>


<code>git pull</code> will show a nice diffst@, so you get an overview of the changes from upstream. <code>git pull —rebase</code> does not do th@ by default. But you want it:
<code>git pull</code> will show a nice diffstat, so you get an overview of the changes from upstream. <code>git pull —rebase</code> does not do that by default. But you want it:


<code>
<code>
  $ git config —global rebase.st@ true
  $ git config —global rebase.stat true
</code>
</code>


To get nicely colored p@ches (from <code>git diff</code>, <code>git log -p</code>, <code>git show</code>, etc.), use this:
To get nicely colored patches (from <code>git diff</code>, <code>git log -p</code>, <code>git show</code>, etc.), use this:


<code>
<code>
Line 125: Line 125:
  $ git config —global alias.co checkout
  $ git config —global alias.co checkout
  $ git config —global alias.ann blame
  $ git config —global alias.ann blame
  $ git config —global alias.st st@us
  $ git config —global alias.st status
</code>
</code>


Line 156: Line 156:
=== Cloning repositories ===
=== Cloning repositories ===


You should clone from the repositories hosted @ "qt.gitorious.org":http://qt.gitorious.org/ or "github.com/qtproject":https://github.com/qtproject/ and track changes from there in order to keep the load on Gerrit down.
You should clone from the repositories hosted at "qt.gitorious.org":http://qt.gitorious.org/ or "github.com/qtproject":https://github.com/qtproject/ and track changes from there in order to keep the load on Gerrit down.


==== Cloning Qt4 ====
==== Cloning Qt4 ====
Line 172: Line 172:
</code>
</code>


Note th@ Qt4 does not have a <code>master</code> branch (since no 4.9 is planned). So, you should push changes to the <code>4.8</code> branch.
Note that Qt4 does not have a <code>master</code> branch (since no 4.9 is planned). So, you should push changes to the <code>4.8</code> branch.


==== Cloning Qt5 ====
==== Cloning Qt5 ====
Line 190: Line 190:
</code>
</code>


It is recommended th@, regardless of the server you use for the initial clone, you use the init-repository script in qt5 to set up the gerrit remote(s) pointing to codereview, and to clone the submodules.
It is recommended that, regardless of the server you use for the initial clone, you use the init-repository script in qt5 to set up the gerrit remote(s) pointing to codereview, and to clone the submodules.


Altern@ively, individual Qt5 submodules can be manually cloned as well. Follow Using Existing Clones above after cloning.
Alternatively, individual Qt5 submodules can be manually cloned as well. Follow Using Existing Clones above after cloning.


Note th@ Qt 5 submodules have been changed from absolute to rel@ive URLs (like "../qtbase.git") in the .gitmodules file.
Note that Qt 5 submodules have been changed from absolute to relative URLs (like "../qtbase.git") in the .gitmodules file.
If you make a clone of git://gitorious.org/qt/qt5 in gitorious as git://gitorious.org/~<username>/qt/<cloned-repository-name>.git the init-repository script will not work.
If you make a clone of git://gitorious.org/qt/qt5 in gitorious as git://gitorious.org/~<username>/qt/<cloned-repository-name>.git the init-repository script will not work.


Line 203: Line 203:
</code>
</code>


==== Cloning Qt Cre@or ====
==== Cloning Qt Creator ====


For "qt.gitorious.org":http://qt.gitorious.org/ :
For "qt.gitorious.org":http://qt.gitorious.org/ :


<code>
<code>
  $ git clone git://gitorious.org/qt-cre@or/qt-cre@or.git
  $ git clone git://gitorious.org/qt-creator/qt-creator.git
</code>
</code>


Line 214: Line 214:


<code>
<code>
  $ git clone git://github.com/qtproject/qt-cre@or.git
  $ git clone git://github.com/qtproject/qt-creator.git
</code>
</code>


Line 225: Line 225:
</code>
</code>


You can't push directly to a branch. So you need to cre@e a review. "refs/for/5.4" means "please submit this as a review for branch 5.4".
You can't push directly to a branch. So you need to create a review. "refs/for/5.4" means "please submit this as a review for branch 5.4".

Revision as of 07:40, 25 February 2015


Setting Up Gerrit

[toc align_right="yes" depth="3"]All projects under the Qt Open Governance umbrella are hosted at "codereview.qt.io":http://codereview.qt.io. These repositories are mirrored on "Gitorious":http://qt.gitorious.org.

How to get started - Gerrit registration

  1. Create an account in the "Qt bug tracker":https://bugreports.qt.io/ (also known as JIRA)
  2. Go to https://codereview.qt.io and log in with your Qt bug tracker credentials
    • Note: Gerrit usernames are case-sensitive, but JIRA usernames are not. If you attempt to log into Gerrit with different capitalizations, you will end up with multiple accounts.
  3. Go to the Settings page: https://codereview.qt.io/settings/
  4. Go to "Settings" -> "Contact Information" and register your email address. You will receive a confirmation email; click on the link inside to finalize your registration.

' Note': Your username and e-mail address will be visible to the public. Use an alias + a custom e-mail address if you want to stay anonymous (this is discouraged)

  1. Go to "Settings"-> "SSH Public Keys" and upload your "public SSH Key":https://help.github.com/articles/generating-ssh-keys , configure username (under contact information), upload public "SSH key":https://help.github.com/articles/generating-ssh-keys
  2. 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.io login <Gerrit username> password <Generated password>


h2. Local Setup

Configure SSH properly (the URLs below rely on this). Add this to your

~/.ssh/config

(Windows:

C:USERNAME%sh\config

):

 Host codereview.qt.io
 Port 29418
 User <Gerrit/Jira username>

NOTE: The following steps need to be applied to every clone:

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

 $ scp -p codereview.qt.io:hooks/commit-msg .git/hooks

or by downloading the file via browser: "commit-msg":http://codereview.qt.io/tools/hooks/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":https://qt.gitorious.org/qt/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" "@quot;

into each <path to git clone>it\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

.

h3. 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 "m@xample.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

A common mistake is forgetting to add new files to a commit. Therefore it is recommended to set up git to always show them in

git stat

and

git commit

, even if this is somewhat slower (especially on Windows):

 $ git config global status.showuntrackedfiles all

Git has a somewhat stupid default that

git push

will push all branches to the upstream repository, which is almost never what you want. To fix this, use:

 $ git config global push.default tracking

This is not relevant for mainline branches under Gerrit control, as all pushing happens with refs anyway, but it may be important for your private clones.

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

Using Existing clones

Add a

gerrit

remote pointing to codereview.

 $ git remote add gerrit ssh://codereview.qt.io/qt/<qt5 or the submodule name you have checked out>

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

 $ git remote add gerrit https://codereview.qt.io/p/qt/<qt5 or the submodule name you have checked out>

For Qt 4.8, use

 $ git remote add gerrit ssh://codereview.qt.io/qt/qt

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

 $ git remote add gerrit https://codereview.qt.io/p/qt/qt

Cloning repositories

You should clone from the repositories hosted at "qt.gitorious.org":http://qt.gitorious.org/ or "github.com/qtproject":https://github.com/qtproject/ and track changes from there in order to keep the load on Gerrit down.

Cloning Qt4

For "qt.gitorious.org":http://qt.gitorious.org/ :

 $ git clone git://gitorious.org/qt/qt.git

For "github.com/qtproject":https://github.com/qtproject/ :

 $ git clone git://github.com/qtproject/qt.git

Note that Qt4 does not have a

master

branch (since no 4.9 is planned). So, you should push changes to the

4.8

branch.

Cloning Qt5

For "qt.gitorious.org":http://qt.gitorious.org/ :

 $ git clone git://gitorious.org/qt/qt5.git

For "github.com/qtproject":https://github.com/qtproject/ :

 $ git clone git://github.com/qtproject/qt5.git
 $ cd qt5
 $ ./init-repository -f no-webkit mirror git://github.com/qtproject

It is recommended that, regardless of the server you use for the initial clone, you use the init-repository script in qt5 to set up the gerrit remote(s) pointing to codereview, and to clone the submodules.

Alternatively, individual Qt5 submodules can be manually cloned as well. Follow Using Existing Clones above after cloning.

Note that Qt 5 submodules have been changed from absolute to relative URLs (like "../qtbase.git") in the .gitmodules file. If you make a clone of git://gitorious.org/qt/qt5 in gitorious as git://gitorious.org/~<username>/qt/<cloned-repository-name>.git the init-repository script will not work.

A URL rewrite rule has to be added to the .gitconfig file:

[url "git://gitorious.org/qt/"]
 insteadOf = git://gitorious.org/~<username>/qt/

Cloning Qt Creator

For "qt.gitorious.org":http://qt.gitorious.org/ :

 $ git clone git://gitorious.org/qt-creator/qt-creator.git

For "github.com/qtproject":https://github.com/qtproject/ :

 $ git clone git://github.com/qtproject/qt-creator.git

Pushing your local changes to gerrit

After you have committed your changes locally, you can push them to Gerrit like this (for example,

5.4

branch):

 $ git push gerrit HEAD:refs/for/5.4

You can't push directly to a branch. So you need to create a review. "refs/for/5.4" means "please submit this as a review for branch 5.4".