Dependencies¶

Before we begin, it’s best to walk through the installation instructions in the Administration Guide. You’ll want to install, at a minimum, the following packages:

• Django (from Subversion)
• django-evolution
• Git
• nose
• paramiko
• patch
• Python Setuptools
• recaptcha-client
• Sphinx
• SQLite

Also install any dependencies for search (if needed) and for repository types that you may want to use.

You will not need to install the Djblets and ReviewBoard packages, as we’ll be doing that in a moment.

Typically on development setups, SQLite is used for the database, as this allows for quick and easy database creation, backups, multiple versions, and deletions.

Apache and lighttpd are usually not used. Review Board contains a built-in single-threaded web server that can be tested against. Unless you’re doing development work that requires a real web server, don’t bother setting one up for this.

memcached can be handy, so install that if you want to, but by default we’re going to use the built-in local memory cache. This is a temporary cache that will persist only as long as the development web server is running.

Djblets¶

Review Board requires the bleeding-edge version of Djblets. This is hosted on GitHub, and you can browse the Djblets repository and see details there.

First, find a nice place where the djblets source directory will live (such as ~/src/) and type the following:

$ git clone git://github.com/djblets/djblets.git

This will download the latest bleeding-edge build of djblets into the djblets directory.

Now to prepare that copy for development use, type the following:

$ cd djblets
$ python setup.py develop

This will create a special installation of Djblets that will reference your bleeding-edge copy. Note that this version will take precedence on the system.

Review Board¶

Review Board installation is very similar to Djblets. It too is hosted on GitHub, and you can browse the Review Board repository.

Go back to your source directory and check out a copy of Review Board:

$ git clone git://github.com/reviewboard/reviewboard.git

This will download the latest bleeding-edge build of Review Board into the reviewboard directory.

You will not need to perform a system installation of this package. Instead, there’s a Python script that will prepare your source directory for development use. You will need to run this:

$ cd reviewboard
$ python ./contrib/internal/prepare-dev.py

If all went well, you will see “Your Review Board tree is ready for development.” Congratulations. You are now ready to start developing Review Board.

RBTools¶

You will need the latest version of RBTools both for development and (as of September 1, 2009) for a version of post-review compatible with http://reviews.reviewboard.org/.

Like Djblets and Review Board, you can find RBTools on GitHub, and you can browse the RBTools repository.

Go back to your source directory and check out a copy of RBTools:

$ git clone git://github.com/reviewboard/rbtools.git

This will download the latest bleeding-edge build of RBTools into the rbtools directory.

Unlike Djblets and Review Board, you will want to install this version, since you will actively use it to post code up for review. You can do this by typing:

$ sudo python setup.py install

This should install a system package of RBTools, ready to use. If you make any changes that you want to test later on, you will need to re-run this command.

Setting up Git¶

Before you make your first commit, you’ll want to configure Git with your name and e-mail address. These will be used in your commits.

Type the following, substituting your name and e-mail address:

$ git config --global user.name "FULL NAME"
$ git config --global user.email emailaddress@example.com

Creating Branches¶

To create a branch based on the upstream master branch, type:

$ git checkout -b new-branch master

This will create a branch called new-branch. You can do all your development on here.

If instead you want to base this on a different branch, put that branch’s name in place of master above. For example, to base something on the upstream release-1.0.x branch, you might type:

$ git checkout -b new-branch release-1.0.x

Switching Branches¶

Switching branches is done with the git checkout command. Simply type:

$ git checkout branch-name

This will switch your existing tree to the files on branch-name.

Making Changes¶

In Git, your local repository is yours to play with. You can commit code to any branch without affecting upstream. Usually it’s best to limit this to branches intended for custom development, and never to the master branch.

This means you can commit as many changes as you want to a branch before posting it up for review, which is really beneficial for large changes.

Before committing, you need to “add” the file(s) you want to commit. This is necessary even for existing files. For example:

$ git add views.py models.py

Once the files are added, you can commit them:

$ git commit

This will open your editor and ask for a change description. Once you’ve provided one and quit your editor, your change will be committed.

As a shortcut, if you want to commit changes to every file you’ve modified, you can type:

$ git commit -a

This has the effect of running git add on every file you modified that exists already in the repository (including new files you added previously in that branch).

Updating from Upstream¶

Over time, and especially before you’re ready to post your change for review, you will want to update it with the upstream changes on master. First, update master itself:

$ git checkout master
$ git pull origin master

Next, merge master in to your branch:

$ git checkout new-branch
$ git merge master

This will merge the upstream changes into your branch. If you have any conflicts to resolve, Git will list them. For each conflict, you will need to edit the file, find the <<<<<, =====, >>>>> lines, and fix fix them. Once each conflict is resolved, git add the file. When you’re done, commit the result.

Additional Tips¶

There is a lot that Git can do, and this guide isn’t going to attempt to cover anything but the basics. It’s highly recommended that you do some reading to get the most out of Git. A good start is the GitHub Guides.

Some people find it helpful to use a graphical repository viewer. Git ships with gitk, which works decently (run with the --all parameter). MacOS X uses may want to try GitX.

Development Web Server¶

Review Board ships with a script that launches Django’s built-in single-threaded web server. While useless in production environments, this server is great for development and debugging. All page requests are viewed in the console that launched the server, as well as any debug printing or logging output.

To launch the web server, run:

$ ./contrib/internal/devserver.sh

This will start the server on port 8080. You should then be able to access your server by visiting http://localhost:8080.

If you need to use a different port, you can always run Django’s development server manually by typing:

$ ./reviewboard/manage.py runserver 0.0.0.0:PORT_NUMBER --adminmedia=reviewboard/htdocs/media/admin/

Specify the port you want to use in PORT_NUMBER above.

Running Unit Tests¶

Both Djblets and Review Board have unit tests that can be run to make sure you don’t break anything. It is important that you run these before posting code for review. We also request that new code include additions to the unit tests.

To run our unit test suite for Djblets, type:

$ cd djblets
$ ./tests/runtests.py

For Review Board, type:

$ cd reviewboard
$ ./manage.py test

If you’re updating the unit tests, you may want to see the Unit Test Fixtures documentation.