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.
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.
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.
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.