Author Archives: krleuschen

Getting up to speed with Review Board

It’s been just over two months since I first started tinkering with Review Board, and I’ve only just begun to really figure out how the pieces I’m working on fit into the larger picture. I don’t consider the slow start a bad thing—Review Board is, after all, a much bigger project than I’m used to seeing at school. I could see early on from the way the application worked, and from the amount of code that backed it up, that I couldn’t possibly expect to understand all the moving parts right away.

I was assigned the task of helping administrators of Review Board installations more easily configure their code repositories. I had worked with Python and Django (the Web framework upon which Review Board is built) a little bit before coming to Review Board, but knowing a bit about a language or framework only gets you so far. I needed to get a feel for the parts of the application I would be working on to understand how my changes would fit in. Luckily, this is a common need for me when I start work on a new project (as it is for most programmers, I think), so I had already picked up a helpful few tricks.

Visualization

Sometimes flipping through code doesn’t cut it for me when I want to figure out the relationships between data models. It’s nice to be able to see the relationshipts. The open-source django-extensions application provides, along with a host of other useful tools, an easy fix: graph_models. Using graph visualization software Graphviz, the graph_models command looks at Django apps’ models and generates a pretty UML-like diagram of its relationships.

Looks a whole lot simpler than the code!

Once generated, you can print it off and tack it to your monitor for quick reference. Although I’ve found it best to pick a subset of Review Board models to look at, you can make a graph of all Review Board models. You’ll just need a big piece of paper to print it on.

With the models I would be working with in hand, it was off to see how they were presented to the user.

Finding your way

Before digging in to code, it’s nice to get a development server running to play around with the application a little bit. However, it’s helpful to see a little bit more of the internals than is normally presented to a user. Another open-source tool, the Django Debug Toolbar (see the installation instructions), is just the ticket. It lets you see how your what your application is doing at a much lower level; it displays debugging information about what HTTP requests are being sent and what the server is doing in response, including (but not limited to) what SQL is being run, which templates are being rendered and which view function/class is handling the request. Using the information the toolbar provides, you get a sense for what is going on behind the scenes, and have a great idea what code to look at if you want to make changes.

After playing around with the pages I though I might be working with, and seeing what data was being passed back and forth, it was time for the fun part…

Hack around, then show your work

Eventually, I know I’m going to have to write some code. At this point though, armed with knowlege of how I think the application works, writing code is no longer a shot in the dark. Granted, it’s still pretty dim and foggy, but at least it’s not pitch black.

After trying some things and succeeding (and, yes, failing), submitting code for review goes a long way to figuring out how my changes should work. In fact, instead of “commit early, commit often”, the Review Board mentors say, and I’m paraphrasing, “review early, review often.” While asking peers and mentors questions helps clear up specific problems I might be having, feedback from a code review let’s me know if I’m on the right track more generally. The review gives mentors an venue to provide hints and suggestions about what direction to take. These hints and suggestions point out things I might have missed or approaches I hadn’t even considered. And all right alongside the code—pretty cool.

Smooth(er) sailing

Now that I have some submitted patches to Review Board under my belt, I feel more confident poking around the code base. Although there’s still a lot I find mysterious about the inner workings of Review Board, it looks far less opaque, and less intimidating, than it did when I first looked.

Advertisements

Review Board and the Django Debug Toolbar

There are a couple of posts on this blog that deal with debugging using the python debugger, pdb (first article and second article). It’s a useful tool, and often beats printing to the console.

While setting breakpoints with pdb is nice if you have an idea where your code might be failing, it can be a bit tedious to use as a first-pass debugging tool. What if a page is loading funny, but no exceptions are raised? Perhaps all you did wrong was misspell a template variable or GET parameter? In this case, it would be nice to be able to quickly look at what your application was doing, from the request to response.

The django-debug-toolbar fills this role nicely. It provides quick and easy access to various, helpful debug information, right from the browser. When the toolbar is installed, a nicely styled, configurable, and collapsable console is displayed off to the side of the page you’re viewing. It offers up information like:

  • HTTP headers
  • Request variables
  • the SQL that was executed when bringing you the current page (also shows the number of queries and time spent on each, great for finding views that overuse the DB)
  • the templates (and the context variables!) that were loaded for the current page
  • Any signals that were sent and their receivers (if any)
  • Logging output and any django.contrib.messages

In addition, installing the toolbar adds the debugsqlshell manage.py command, a tool that displays the SQL generated by the Django ORM.

Getting the toolbar running is simple. First, install the toolbar in your Review Board virtualenv (if you’re not using virtualenv, here are some instructions on how to get it up and running):

$ pip install django-debug-toolbar
# or
$ easy_install django-debug-toolbar

Next, open up settings_local.py (the place for your custom Review Board application settings. It should be in the project root directory—if it’s not you might need to run ./contrib/internal/prepare-dev.py from the project root to have it created for you). Add the following lines:

from settings import RB_EXTRA_APPS, RB_EXTRA_MIDDLEWARE_CLASSES

RB_EXTRA_MIDDLEWARE_CLASSES += [
'debug_toolbar.middleware.DebugToolbarMiddleware'
]
RB_EXTRA_APPS += ['debug_toolbar', 'django_extensions']

DEBUG_TOOLBAR_CONFIG = {
# Intercepting redirects inserts an intermediate page between a redirect,
# so you can inspect the request and/or response. It's usually not
# necessary, so keep it out of the way by overriding the default
# configuration.
'INTERCEPT_REDIRECTS':False,
}

Finally, fire up the dev server and the toolbar should be there. Have a look at some of the third-party panels for some more specialized debug information that might be useful.

Status Report — October 21st, 2012

Wesley Ellis

Currently:

  • Still working on build plugin for reviewbot

Roadblocks:

  • None

Next:

  • Write some code for the build plugin

Jesus Zambrano

Currently:

  • Trying to get a better understanding of reviews.js and datastore.js

Roadblocks:

  • None.

Next:

  • Modify the bit in datastore.js that makes the server request when discard draft button is clicked.

Allyshia Sewdat

Currently:

  • Trying hard to get a functional patch in for preliminary review (adding JSLint plugin to ReviewBot). Considering just submitting half functional code to get some pointers but am trying to submit a working patch for proof of concept.

Roadblocks:

  • Can’t seem to call JavaScript file with arguments via command line with SpiderMonkey the way I’d need to. Looking for a workaround. Wondering if using more capable (but less light weight) JS engine like Node.js (which is more than an engine) would be appropriate.

Next:

  • Solve the above mentioned issue and commit.

Questions:

  • Thoughts on how tolerant we’d be of using a new module (python-spidermonkey) to facilitate calling JS functions in Python?

Aamir Mansoor

Currently:

  • Continue working on pluggable UI for Markdown. Specifically, working on the Backbone.js view and model to render contents of a Markdown file

Roadblocks:

  • None

Next:

  • Parse Markdown in Django using the “Markdown” package

John Sintal

Currently:

  • Working on rb diff and waiting for feedback.
  • Installed pep8 and pylint on my IDE Geany.

Roadblocks:

  • None

Next:

  • Wrap on rb diff and move to a new command.

Questions:

  • What would be my next command?
  • What kind of testing do you expect for these commands? (If any are needed)
  • Is tracking-branch and parent already support for my rb diff? I think it is by the options, but I’m having trouble testing it out.

Karl Leuschen

Currently:

  • Working on generalizing the key association that’s been roughed out for GitHub hosted repositories. A work-in-progress review is open (r/3429) for the feature branch, and have gotten some good feedback already.

Roadblocks:

  • None.

Next:

  • Decide on how to keep track of repositories that have an associated key, then implement and test. Start working out how it will all look from the web interface.

Tina Yang

Currently:

  • Trying to send out an in-progress code review for associating a FileAttachment with a binary FileDiff.

Roadblocks:

  • None.

Next:

  • Make the main file attachment list filter out FileAttachments that is associated with a FileDiff.

Michelle Chuang

Currently:

  • Continue working on pluggable UI for Markdown. Specifically, working on the Backbone.js view and model to render contents of a Markdown file
  • Addressing the code review comments for issue 2552
  • Continuing to work on Pluggable UIs for images. Still need to set up the backend to view image comparisons and work on the actual image diffing.

Roadblocks:

  • None.

Next:

  • Figure out how the various image diffing views are implemented.

Sampson Chen

Currently:

  • Confirmed on using Docutils for RST, and Markdown 2.2.0 for .md.
  • Coordinated with Aamir: I will implement RST rendering for thumbnails with Docutil and he will implement Markdown for rendering .md in pluggable UI; then we will teach each other what we learned about each API (overall flow, hints, tips etc), and swap (i.e. I will then work on thumbnails for .md, and he will work on pluggable UI for RST)
  • Looked into Docutils’ architecture and particular the publisher API. Now implementing the calls into thumbnails infrastructure.
  • Getting started on blog post.

Roadblocks:

  • None

Next:

  • Hopefully finish implementing thumbnail rendering for RST at least by Sunday night.

Meeting Minutes for October 14th, 2012

Announcements:

No Review Board announcements.

Questions / Answers / Tips:

Q (Aamir) What is the scope of the Pluggable UI project, with respect to text-based files (e.g. Markdown, reStructuredText)?
A: The goals of the project should be to allow rendering, diffing (already supported by RB) and potentially spell-checking for text-based formatting language files. As a plus, it would be nice to be able to toggle between rendered and raw versions of the file.

Q (Allyshia) When is UCOSP considered over?
A: Roughly the first week of December. However, it varies for each university, so check with your course instructor / UCOSP liason at your school.

Q (John) Any updates on the state of the base class and rbpost?
A: The base class is there, and should run commands which have be defined in the entrypoints. rbpost isn’t functioning fully yet, but all the parts of interest should be available soon (hopefully by Oct 15).

Q (Karl) Should repository SSH key association be available/automatic when adding repositories via the API?
A: It would be nice, but may not be feasible. ChipX86 may be able to say for certain.

Q (Michelle) Which files would be good to look into for image diffing?
A: Other front-end diff handlers are in diffviewer.js, and should be a good place to start, even if the structure may have changed with the addition of Backbone.js. As for image types to handle, anything with a image/* MIME type would be nice.

Q (Sam) How will the recent changes to the pluggable UI projects affect how thumbnails for text are handled?
A: They won’t — use the same, existing thumbnail rendering.

Q (Sam) Can we use the Markdown and docutils python libraries (from PyPI)?
A: Most likely. docutils is already part of the RB dependencies, and a markdown library will be a necessity for rendering. Double-check with purplecow and/or ChipX86 to be sure.

Q (Wesley) Is there any preference for specific build bot systems? If not, is it alright to write a Jenkins plugin for RB?
A: No preference. A Jenkins plugin would be fine.

Q (Tina) Are there some simple tests/checks that can be run when something goes wrong with Reviewboard, before drilling down into debugging?
A: It depends on the situation, but here a few that might be useful

  • If you just pulled, and everything is broken, pull in the latest changes to djblets and rbtools, then run python setup.py develop. This should rule out changes to dependencies.
  • Ask others to see if the problem is affecting them as well.
  • Check your DB — run ./reviewboard/manage.py syncdb, and check to see if any database migrations need to be run (via Django evolution)
  • Try restarting your development server.

An expanded list of these kinds of tips might make for a good blog post.

Q (Sam) What’s the difference between a patch and a review request?
A: A patch is submitted code that fixes a bug or adds a feature. A patch is contained within a review request, but a review request does not necessarily imply a patch. A review request sometimes just contains screenshots, for example.

Any tips for fitting Reviewboard into a busy schedule?
A: Finding free slices of time to work on Reviewboard can be tough. So, set aside a dedicated chunk of time where you can work on Reviewboard uninterrupted.Having a block of time to work with makes it easier to get in the zone: you avoid inefficient context switching, and you’re more likely to be able to get a back and forth going on IRC.

More tips:

  • Find a place with no distractions (don’t work where you sleep).
  • Breaking up your job into tasks that can be performed independently is also good, so if you get blocked on one, you can ask your question, and work on the other task until you get unblocked.