Fri 15 Feb 2008

Preparing For The Next Django Sprint

In a little over four weeks (17 March in the US), Django will have another one of our code sprints. The 'main event' will be in Chicago, USA, where a bunch of people will be taking advantage of the post-PyCon sprint sessions for three days. However, as always, remote participation is possible and encouraged.

Somebody recently asked on django-users what they could to prepare for the sprint, since this was going to be their first time. Jacob has promised to give an introductory tutorial on the day in Chicago, which will help those present in person. For others, here are my thoughts on how to prepare (and why now isn't too early to start if you want to get some real work done).

What Not To Do

From IRC during the September Django sprint:

EyePulp_: I've got my sweatbands on.  I'm ready-to-sprint.
malcolmt: thanks. It'll take some time for that image to go away.
EyePulp_: and leg warmers - I'm pretty much Flashdance here.
malcolmt: please stop talking now

Too much sharing right there. Enough said.

Choose Your Own Adventure

What you want to work on during the sprint and how much time you want to devote to it is entirely up to you. Nobody else is going to assign you things to do. We don't know what your skill level, either in the arena of Python coding or understanding the broader items required to implement a particular features. For example, if you're going to work on HTTP problems, it's probably worthwhile having a reasonable familiarity with the HTTP specification (or at least know where to look it up).

Every sprint, people show up and ask "what should I work on?" Personally, I always find this very hard to answer beyond general suggestions. Unfortunately, it's also a little difficult to make a quick decision, sometimes. Sure, you can go hunting for low-lying fruit and knock off a few quick things. Sometimes it's hard to find those things, though. So, a few suggestions (and if you don't agree with my suggestions, that's excellent: you should definitely feel confident and comfortable in picking anything that interests you).

(Non-)Suggestion #1: The answer to your question is not "write documentation." Writing documentation isn't necessarily easy. You need to truly understand the area you're writing about so that you can distil it down to something that is complete, correct and concise. And then you have to get it past Adrian. Play a few levels of Super Mario Galaxy to get a feeling for what that last step is like (but in a good way). Also, Django won't stop being useful if there are a few tiny spelling errors in the existing documentation, so, yeah, that's useful work but is it really the most enjoyable way to spend a few evenings coding at home during the sprint? Everybody's going to try and work on documentation. Be different; pick something fun and neglected.

Suggestion #2: Have a look at the full list of open Django tickets. I've grouped this list by component for a reason. You'll often find that the first ticket in a new area is a little tough to solve, but once you've done all the hard work to understand that one, others in the same are are much easier. Also, you can sometimes spot patterns — a group of tickets that aren't necessarily identical, but seem to be in the same area of code. Maybe they're disguised versions of a larger problem, or maybe it's just an area of code that needs some attention. You can do this on the day, or beforehand if you want to do some preparation.

Browse through the list by component and find an area that appeals to you. Unless you want to work on newforms-admin, skip over any in the Admin section. Similarly, database tickets marked with qs-rf or that are related to constructing SQL are best left alone for the moment unless you want to dig in on the queryset-refactor branch (which will hopefully be finished before PyCon). If you're prepared to do a bit of preparatory work, you can use this as a chance to learn about a new area, even. None of Django's code is impossible to understand, given a bit of serious application and enough time. You might not want to start writing fixes before you can get some help during the sprint, but you might have a few hours beforehand to spend an evening or two reading through the code in your area of choice and trying to work out how it fits in with things.

Write some little applications to test the area you want to work with. Not just things that fail as described in a bug. But things that work, too. It's all too common for people to submit a patch that might well fix the bug they were addressing, but breaks two or three other use-cases. Playing with an area of the code by writing application code that uses it is a good way to gain familiarity as well as have a little block of applications you can use to test any changes against (if they used to work and now they don't, after applying a patch, that's usually a bad sign).

Finally, if you think you might want to work in one particular component, spend a little while using Google's archives of django-developers and django-users to see if anything's been discussed on that area in the past. In the preparation phase, maybe just bookmark any interesting looking posts. Then when you come to work on this, you can see what directions might have been suggested or what the idea behind a particular feature might be.

This type of preparation work isn't the same as starting early on the sprint. It's more a matter of getting your brain ready to site down and tackle some problems. Rather than spending half a day deciding what to do, you'll already have a bit of an idea about where you could do some work and what the bigger picture looks like in that area.

Suggestion #3: Make sure your laptop or desktop machine is ready for work beforehand. If you're going to be writing patches for Django, you're going to have to be able to test them. This means being able to run the test suite. Read the unit-testing section in contributing.txt because people forget to create settings files and the like.

In fact, read the whole contributing document and pay attention to the coding style guidelines and the stages a ticket goes through. Each sprint, we get a few people who are confused about what to do once they submitted a patch (very little) or why we ask for some style changes.

It's worth trying to have access to more than just SQLite when you're wanting to test things. If you also have either MySQL or PostgreSQL installed, some problems will show up earlier. It takes a little longer to run the tests against those, since they have to write to disk (instead of using SQLite's in-memory database), so you only check them every now and again, but it's handy to have around. Trying to set that up on the day could easily chew up a few hours and do you really want to spend the time when you could be "interacting"?

For bonus points, build a couple of older versions of Python (2.3, particularly) and maybe just the SQLite wrapper for it so that you can run the tests against Python 2.3. Django is still Python 2.3 compatible, but every now and again we let something slip through. For after-the-fact checking, there's always the Buildbot, which includes Python 2.3 + SQLite amongst it's clients. Ironically, as I write this, I notice there's a 2.3 failure from something I checked in a while back (not sure why it's failing, though). Kind of proves my point in an embarrassing fashion.

You might even like to have a very recent Jython available if you swing that way. Django has quite a nice symbiotic relationship with Jython at the moment. They give us patches to make it run on Jython and we provide something they really want to run on Jython so they work out what features need to be added.

Suggestion #4: Be realistic about how fast things will go. Code sprints can seem like fairly hectic periods, depending on what you're doing. Keep in mind that the more experienced people, particularly the maintainers with the power of committing things or asking for patch improvements, are going to be busy as they try to multitask. So you may not get immediate attention when you need help, although you will always be able to find somebody to offer some advice eventually. This means if you're going to try and tackle a really big issue that might require some design discussion, trying to do it remotely during the sprint might be a little optimistic. There's a reasonable chance you'll pick an approach that will be quite different to what we had in mind. That's not a tragedy, but it's always a shame to have to ask somebody who's put in a lot of work to go in a different direction that means throwing away a lot of their code.

This also means being a little wary of tickets marked "design decision needed." Some of us will make a run through that list and try to reduce it, time permitting prior to the sprint, but there are always going to be controversial tickets on there. Very few of them are show stoppers to Django moving forwards, though (or, if they are, somebody's already working on it in some fashion).

Suggestion #5 (something easier): Okay, you really want to contribute in some way, but don't feel brave enough to tackle something entirely new. So tackle something old. Seriously. Look for tickets that are in the "accepted" state and have patches attached (you can filter on "has patch"). Try to work out why it hasn't been moved to "ready for checkin" yet. It might be because (a) the patch is a little old and no longer applies cleanly. Update the patch. Or (b) it needs documentation or is something we might be able to reasonably test and is worthwhile adding to the test suite. Or (c) nobody's had a chance to look at it yet. For this last one, although you should usually let the experienced triagers decide when to move to "ready for checkin", it always helps to have a few people try out a patch and see if it works. Try to break it. I mentioned above that people can be a bit blinkered when they write a patch: they fix the problem they can see, but forget to notice if they've caused any collateral damage. So think of things that used to work that might be broken by this patch.

Suggestion #6 (also fairly easy): Go through tickets in the "unknown" component and try to find a better component for them. That will help people working on suggestion #2, for a start.

Suggestion #7 (be a tester): Go through tickets in the "unreviewed" state and see if (a) the description makes sense and you can understand the problem, (b) you can repeat the problem. Quite often somebody will file a ticket that documents a problem they've been trying to diagnose for some hours. They'll forget to include information that is quite familiar to them, but unknown to everybody else. So you may find that a ticket lacks the necessary steps to repeat it. A problem that cannot be repeated, cannot be fixed.

Also, you'll sometimes find help requests in the ticket tracker (although we usually catch those). They can be quietly closed with a note pointing the person to django-users for support help.

Suggestion #8 (for foreign language speakers): Have a look at the list of languages that Django has been translated into. A bit before the sprint, I'll try to find time to put up a list of the percentage coverage in each language. If you speak one of the languages that isn't very well translated, or isn't translated at all, lend us your skills. There are many areas of the world where Django isn't providing good coverage at all. Slightly unfortunate if you live anywhere in Africa, for example, unless you're in one of the areas that speaks English or French. Our African language coverage is fairly woeful. European coverage is fairly good (both eastern and western), but there are a lot of Asian countries that have languages we don't speak yet. So the sprint might be a good time to become a new translator.

This has become a lot longer than I intended. Mostly, I want to get across the idea that there is some useful preparation you can do for something like a code sprint. It won't take a lot of time, but it might save you half a day of feeling unprepared at the start. It's not too early to be thinking about whether you're set up to work, since it might take a week or two to be able to set aside an evening or a Sunday afternoon to do that preparation.

Topics: software/django