These are two guides I would love to have time to write -- an introduction
to the codebase, and a How To on writing SCMTools.
I'll give you a bit of a summary here, though. If you search through the
archives, you may find other tidbits of information too.
Let's start with the codebase.
We follow many of the Django conventions on the structure of a project. Each
directory in the main "reviewboard" directory is an "app directory."
Basically, a segmented part of the codebase, each with its own
responsibility. They're as follows:
* accounts - Account handling (user profile, registration, logging in, etc.)
* admin - Administration UI and general sanity checks for the site
(dependencies and such)
* changedescs - Code for processing and storing change descriptions on
* cmdline - The actual code for rb-site and some other things.
* difffviewer - Diff viewer code. Diff parsing, syntax highlighting, types
of change analysis (move detection, function/class headers), Upload Diff
* notifications - E-mail notifications for changes
* reports - Very simple reporting functionality. You won't need this, and
it'll go away/move at some point.
* reviews - Review request, review, commenting, dashboard, and other things.
* scmtools - Code for talking to a repository and configuring repository
entries. This is what you'll be most interested in.
* site - Code for segmenting an installation into multiple virtual sites.
It's only in 1.6, and is more of a special-case feature.
* templates - The actual HTML templates that make up the site
* webapi - All the public REST API stuff
In the directories, you'll commonly find:
* admin.py - Representations of models in the admin UI
* forms.py - Representations of HTML forms. Includes validation and
processing of the data.
* models.py - Classes that model database tables, along with utility
functions. These are the main things that other code interacts with, in
order to query or modify the database.
* urls.py - URL mappings, pointing URLs to views
* views.py - Code that renders a page, given some data and a template.
There are others as well, but those are the common ones.
Now, let's get to the core of what you want. SCMTools.
An SCMTool is the interface between Review Board and a repository. It's
actually not inherently complicated, but it does depend on what you can
easily do with the repository and how.
SCMTools have the following responsibilities:
* Accessing a file, given a file path and a revision
* Checking the validity of a repository configuration.
* Grabbing file and revision information from a diff.
The first two are generally no big deal. Where people get tripped up
sometimes is the third. Review Board expects that all uploaded diffs contain
enough information for grabbing exactly the source file from a repository.
That means the diff must contain a file path and a revision.
If this is your own source control system, and you are generating your own
diffs, I'm sure you can control this to some degree. When this is beyond
people's control, though, the solution is to update the 'post-review' tool
and have it generate a custom diff with this information inserted.
It's typical to put the revision in the "date" fields in a diff. Like:
--- /path/to/file.py revision
+++ /path/to/file.py whatever
Some, like Git, provide this as a custom line before the "---" and "+++"
lines. So it's up to whatever you guys end up using.
Now, the best thing you can do is to go over the other SCMTools classes and
look at how they work. Try to figure out what your internal SCM is closest
to in terms of functionality, and mostly duplicate that.
Key functions to implement:
* get_file - Must return file content, given a file path and revision. The
revision may be HEAD, UNKNOWN, or PRE_CREATION (new file).
* file_exists - If you have a way to check the existence of a file without
having to grab the full file content, use this. Otherwise, it will call
get_file and check the result.
* parse_diff_revision - Takes a file path and revision string and returns a
revision. This can return the revision number/string, HEAD, or PRE_CREATION.
* get_changeset - If your SCM supports server-side changesets (defined as
the server having knowledge of the opened files on all clients, with
descriptions of the change -- usually this isn't needed).
* get_fields - This will return a list of field names to display in the New
Review Request or Upload Diff forms. This is at least "diff_path" but you
may want "parent_diff_path" if you want to present a "Parent Diff" field. A
parent diff is a diff between some upstream revision and a branch you're on,
which will be applied before your main diff is applied. Typically used for
DVCS systems like Git.
* get_parser - Returns a DiffParser subclass for parsing the fields of your
Again, go through the other ones and see how that's sort of put together.
It's hard to know what you need me to focus on without knowing details of
your SCM, so at this point I think I'll just let you ask any questions and
I'll describe them in more detail :)
Christian Hammond - chip...@chipx86.com
Review Board - http://www.reviewboard.org
VMware, Inc. - http://www.vmware.com
On Wed, Jan 26, 2011 at 8:06 PM, Anshul <anshul14ran...@gmail.com> wrote:
> Hi ,
> I am trying to integrate VSS and an internal SCM of my company with
> ReviewBoard. I am kind of short on time and unable to find any good
> walk through on integrating a new SCM with ReviewBoard.
> Specifically, what all files would i need to modify/add in order to
> add a new repository from scratch.
> (one place i did figure out was that I need to add a new file in
> Another thing of great help would be a structural overview of
> Reviewboard (as in files/directory mapping with the functionalities)
> for new developers to quickly add new features or modify existing
> It would be a great help to me , if in case such pointers are already
> available in some blog / mailing list / wiki, !
> Want to help the Review Board project? Donate today at
> Happy user? Let us know at http://www.reviewboard.org/users/
> To unsubscribe from this group, send email to
> For more options, visit this group at
Want to help the Review Board project? Donate today at
Happy user? Let us know at http://www.reviewboard.org/users/
To unsubscribe from this group, send email to
For more options, visit this group at