Infrastructure/Review Board: Difference between revisions

From KDE Community Wiki
*>Sandstrom
(Add a section on creating a Git alias for post-review)
No edit summary
 
(19 intermediate revisions by 13 users not shown)
Line 1: Line 1:
{{Warning|This page is heavily outdated and should only be used for historical context. The reviewboard no longer exists.}}
KDE currently uses the [http://www.reviewboard.org/ Review Board] software for performing reviews on code changes.
= KDE Review Board =
= KDE Review Board =


KDE currently uses the [http://www.reviewboard.org/ Review Board] software for performing reviews on code changes.
There are separate versions of Review Board for use with Git and Subversion:
* [https://git.reviewboard.kde.org KDE Git Review Board]
* [https://svn.reviewboard.kde.org KDE Subversion Review Board]
 
Note that https://reviewboard.kde.org/ redirects to the Git version.
 
== Getting an account ==
 
You'll need a [https://identity.kde.org/ KDE Identity Account] in order to upload patches to Review Board. If you don't already have one, see [[Infrastructure/Get_a_Developer_Account#KDE_Identity_Account]].
 
== Using Review Board the easy way ==


There are separate versions of Review Board for use with Git and Subversion:
This way may not be as powerful as the one explained below, so if you are a power user you may want to read the next sections to make your workflow faster.
* [http://git.reviewboard.kde.org KDE Git Review Board]
* [http://svn.reviewboard.kde.org KDE Subversion Review Board]


Note that http://reviewboard.kde.org/ redirects to the Git version.
Review Board works on a patch basis, so you need to have a patch to upload to the web page. The simplest way to achieve that is
* Code in git/svn in the branch you want to change
* Do a git/svn diff and store the diff into a file (pipe it with '>')
* Upload the diff to Review Board


== Using Review Board and post-review with Git ==
== Using Review Board and rbt with Git ==


Every Git Project repository has its own entry on the KDE Git Review Board.
Every Git Project repository has its own entry on the KDE Git Review Board.
Line 25: Line 39:
  git merge master
  git merge master


=== Using post-review to post changes for review ===
=== Using rbt to post changes for review ===


Once you are done with the above, it is time to post the changes to ReviewBoard. The easiest and most comfortable way to do that is <tt>[http://www.reviewboard.org/docs/manual/dev/users/tools/post-review/ post-review]</tt>, a handy command line tool which takes care of creating review requests for you. This is normally in a package called RBTools (openSuse has a 1-click package in the [http://software.opensuse.org/search?q=rbtools devel:tools repository])
Once you are done with the above, it is time to post the changes to ReviewBoard. The easiest and most comfortable way to do that is [https://www.reviewboard.org/docs/rbtools/dev/ rbt], a handy command line tool which takes care of creating review requests for you. This is packaged in most distributions:
 
* OpenSuse: [http://software.opensuse.org/search?q=rbtools rbtools] in the <code>devel:tools</code> repository
* Fedora: <code>sudo dnf install RBTools</code>
* Debian / Ubuntu: <code>sudo apt-get install python-rbtools</code>


==== Prerequisites ====
==== Prerequisites ====


The following has to be done only once to make your local clone fit for use with <tt>post-review</tt>.
The following has to be done only once to make your local clone fit for use with <tt>rbt</tt>.


First of all, you have to tell it about the ReviewBoard server. If your project does not ship with a <tt>.reviewboardrc</tt> file (encourage the project manager to add one!), the first thing you have to run is:
First of all, you have to tell it about the ReviewBoard server. If your project does not ship with a <tt>.reviewboardrc</tt> file (encourage the project manager to add one!), the first thing you have to run is:
Line 39: Line 57:
ReviewBoard currently only knows the project repositories by their git:// URLs, making it necessary to have a remote using the git:// URL in your clone. If your <tt>origin</tt> remote is already using the git:// URL, you are all set. If not you need to add another remote now.  
ReviewBoard currently only knows the project repositories by their git:// URLs, making it necessary to have a remote using the git:// URL in your clone. If your <tt>origin</tt> remote is already using the git:// URL, you are all set. If not you need to add another remote now.  


Let's suppose you are looking to have some changes to [https://projects.kde.org/projects/extragear/multimedia/amarok Amarok] reviewed, and the URL of your <tt>origin</tt> remote is <tt>[email protected]:amarok</tt>. To add another remote using the git:// URL you might run:
Let's suppose you are looking to have some changes to [https://projects.kde.org/projects/extragear/multimedia/amarok Amarok] reviewed, and the URL of your <tt>origin</tt> remote is <tt>[email protected]:amarok</tt>.
 
git remote add anonupstream git://anongit.kde.org/amarok
git fetch anonupstream
 
If your <tt>origin</tt> remote was already using the git:// url, substitute <tt>anonupstream</tt> with <tt>origin</tt> throughout the rest of this tutorial.


==== Creating the review request ====
==== Creating the review request ====


You are now ready to create the review request. The <tt>post-review</tt> command should look something like this:
You are now ready to create the review request:


  post-review --parent=master --tracking-branch=anonupstream/master
  rbt post


This command tells <tt>post-review</tt> that your branch is based upon <tt>master</tt>, and it is set to track the remote branch <tt>anonupstream/master</tt>. You can also give <tt>post-review</tt> some more arguments to avoid using the web interface later - have a look at the [http://www.reviewboard.org/docs/manual/dev/users/tools/post-review/ user manual] for more on that.
This command tells <tt>rbt</tt> to post all changes on your <tt>master</tt> branch which are not present on the remote branch (usually <tt>origin/master</tt>). You can also give <tt>rbt</tt> some more arguments to avoid using the web interface later - have a look at the [https://www.reviewboard.org/docs/rbtools/dev/ user manual] for more on that.


After the command has been run a web address will be shown in the terminal, pointing at your review request.
After the command has been run a web address will be shown in the terminal, pointing at your review request.
Line 58: Line 71:
==== Updating a review request ====
==== Updating a review request ====


If you need to update an existing review request you can invoke <tt>post-review</tt> with an additional <tt>-r</tt> argument, which should be the numeric id of the review request you want to update. Supposing you want to update review request 54, you would run:
If you need to update an existing review request you can invoke <tt>rbt post</tt> with an additional <tt>-r</tt> argument, which should be the numeric id of the review request you want to update. Supposing you want to update review request 54, you would run:


  post-review --parent=master --tracking-branch=anonupstream/master -r 54
  rbt post -r 54
 
==== Create a convenient git alias ====
 
To reduce the typing needed you can create a git alias with the options you use for post-review. Add the line
below to the <tt>[alias]</tt> section of your ~/.gitconfig file.
 
post-review = !post-review --guess-summary --guess-description --username=<YOUR USERNAME> --parent=master --tracking-branch=origin/master
 
Now you can submit a committed patch for review by just typing
 
git post-review
 
If you want to amend an already existing review request just add <tt>-r NUM</tt> to the end of the command.


==== Creating a ReviewBoard-compatible diff ====
==== Creating a ReviewBoard-compatible diff ====
Line 79: Line 79:
In some rare cases you simply want to generate a diff and submit it to ReviewBoard later. You can do that by running:
In some rare cases you simply want to generate a diff and submit it to ReviewBoard later. You can do that by running:


  post-review --parent=master -n > your-patch.patch
  rbt diff --parent=master > your-patch.patch


=== Closing a review request ===
=== Closing a review request ===


To close a review request, you can either use the ReviewBoard web interface or more conveniently, right in a commit. This is done by using the REVIEW keyword followed by the review ID you want to close. For example, to close review 54, you would put
A review request can be closed in two ways. Either the user who opened the review request can use the ReviewBoard web interface. Or you close the review right in a GIT commit. This is done by using the REVIEW keyword followed by the review ID you want to close in a separate line. Add a description of the fix in the following lines. For example, to close review 54, you would put


Fixing crash due to an uninitialized pointer when opening a file
  REVIEW: 54
  REVIEW: 54


in your commit. A message will also be posted to ReviewBoard indicating the commit SHA1 that closed the request.
in your commit. A message will also be posted to ReviewBoard indicating the commit SHA1 that closed the request. Please note that this only works for GIT commits, and not for Subversion commits.
 
You can use this command to add REVIEW keyword to existing git log:
git rebase --interactive


== Using Review Board With Subversion ==
== Using Review Board With Subversion ==
Line 103: Line 107:
After you completed the form, a notification mail will be sent to the developers and they will answer you.
After you completed the form, a notification mail will be sent to the developers and they will answer you.


/!\ You need to use svn diff in english, if your system is not english, please do LC_ALL=C svn diff
/!\ You need to use svn diff in English, if your system is not English, please do LC_ALL=C svn diff

Latest revision as of 05:45, 16 January 2023

Warning

This page is heavily outdated and should only be used for historical context. The reviewboard no longer exists.

KDE currently uses the Review Board software for performing reviews on code changes.

KDE Review Board

There are separate versions of Review Board for use with Git and Subversion:

Note that https://reviewboard.kde.org/ redirects to the Git version.

Getting an account

You'll need a KDE Identity Account in order to upload patches to Review Board. If you don't already have one, see Infrastructure/Get_a_Developer_Account#KDE_Identity_Account.

Using Review Board the easy way

This way may not be as powerful as the one explained below, so if you are a power user you may want to read the next sections to make your workflow faster.

Review Board works on a patch basis, so you need to have a patch to upload to the web page. The simplest way to achieve that is

  • Code in git/svn in the branch you want to change
  • Do a git/svn diff and store the diff into a file (pipe it with '>')
  • Upload the diff to Review Board

Using Review Board and rbt with Git

Every Git Project repository has its own entry on the KDE Git Review Board.

Creating your changeset

To create your changeset, you probably want to work in a separate branch - or even in your clone. This is actually suggested and the proper way to do changesets in Git. You can create any number of commits, amend them, and do whatever you want to do - it won't affect the next steps, as you will submit the whole branch for review.

Before proceeding it is good practice to rebase your branch onto the branch you want to target for the merge. So, supposing you want to target master, make sure it is up-to-date with the remote and then run, and want to publish a review for a local branch:

git pull --rebase

If you want to post a review for merging a non local branch, you might want to run the following:

git merge master

Using rbt to post changes for review

Once you are done with the above, it is time to post the changes to ReviewBoard. The easiest and most comfortable way to do that is rbt, a handy command line tool which takes care of creating review requests for you. This is packaged in most distributions:

  • OpenSuse: rbtools in the devel:tools repository
  • Fedora: sudo dnf install RBTools
  • Debian / Ubuntu: sudo apt-get install python-rbtools

Prerequisites

The following has to be done only once to make your local clone fit for use with rbt.

First of all, you have to tell it about the ReviewBoard server. If your project does not ship with a .reviewboardrc file (encourage the project manager to add one!), the first thing you have to run is:

git config reviewboard.url https://git.reviewboard.kde.org

ReviewBoard currently only knows the project repositories by their git:// URLs, making it necessary to have a remote using the git:// URL in your clone. If your origin remote is already using the git:// URL, you are all set. If not you need to add another remote now.

Let's suppose you are looking to have some changes to Amarok reviewed, and the URL of your origin remote is [email protected]:amarok.

Creating the review request

You are now ready to create the review request:

rbt post

This command tells rbt to post all changes on your master branch which are not present on the remote branch (usually origin/master). You can also give rbt some more arguments to avoid using the web interface later - have a look at the user manual for more on that.

After the command has been run a web address will be shown in the terminal, pointing at your review request.

Updating a review request

If you need to update an existing review request you can invoke rbt post with an additional -r argument, which should be the numeric id of the review request you want to update. Supposing you want to update review request 54, you would run:

rbt post -r 54

Creating a ReviewBoard-compatible diff

In some rare cases you simply want to generate a diff and submit it to ReviewBoard later. You can do that by running:

rbt diff --parent=master > your-patch.patch

Closing a review request

A review request can be closed in two ways. Either the user who opened the review request can use the ReviewBoard web interface. Or you close the review right in a GIT commit. This is done by using the REVIEW keyword followed by the review ID you want to close in a separate line. Add a description of the fix in the following lines. For example, to close review 54, you would put

Fixing crash due to an uninitialized pointer when opening a file
REVIEW: 54

in your commit. A message will also be posted to ReviewBoard indicating the commit SHA1 that closed the request. Please note that this only works for GIT commits, and not for Subversion commits.

You can use this command to add REVIEW keyword to existing git log:

git rebase --interactive

Using Review Board With Subversion

Not all KDE Subversion projects use Review Board so first you need to check if the project you've created the patch for is actually using reviewboard. For this, go to the groups section and see if the project's group is listed there. If it is listed there, you should use the reviewboard, otherwise send the patch by other means.

For sending a patch, you first need to register. Then simply click New Review Request and fill out the form. The most important parts of the form are:

  • The actual patch. You need to upload the patch you've created earlier here
  • The SVN base path. This is needed for the inline patch display to work. This can be a bit tricky, if you are unfamiliar with KDE's SVN layout, check WebSVN. For example, if you're svn diff'ing from /path/to/your/copy/of/kdelibs/cmake/modules, the base path should be /trunk/KDE/kdelibs/cmake/modules. If you still don't know the correct base path, ask a developer on IRC. You can also edit the review request later.
  • A summary of the patch. This should be short, it will show up as subject of the notification emails.
  • A description of the patch. This can be longer.
  • The group(s). Make sure you enter the correct group ID here, as seen earlier on the groups page.

After you completed the form, a notification mail will be sent to the developers and they will answer you.

/!\ You need to use svn diff in English, if your system is not English, please do LC_ALL=C svn diff