Second edition

So just after lunch today a box arrived, containing copies of the second edition of Practical Django Projects, which went through final editing about a month ago (Apress tends to be pretty quick at getting the book printed and shipping). Since I assume that means other people will be getting copies of the book soon, I’d like to cover a couple important bits of information.

First of all, the second edition (as the cover proudly declares) covers Django 1.1. Which hasn’t yet released. There are three actual bugs still open against the 1.1 milestone, as well as a variety of documentation fixes, so hopefully we’ll have a release candidate soon and a final release about a week after that. In the meantime, your best bet is a Subversion checkout of current trunk, because there’s at least one thing described in the book that didn’t make the beta release.

Second, this isn’t simply an update of the original text; there’s new material, including an entirely new chapter on development techniques and useful third-party tools which writes up some things that I don’t think have ever appeared in official documentation or in other books on Django.

Third, and most important: the first edition pretty much sucked in terms of being able to get at the code. There was supposed to be a downloadable package containing the code covered in the book, but it ran into a major problem: Django 1.0 released a couple months later, and — since there wasn’t yet a backwards-compatibility guarantee — a number of things changed between the time I signed off on the book’s contents (May) and the time Django 1.0 landed (September). This left two options for providing a code package, neither of them acceptable:

Simply package up exactly the code that appeared in the book. This would have matched the book’s contents, but would have been useless to anyone following along after the Django 1.0 release, because large swathes of it simply wouldn’t have worked. Update the code to work on Django 1.0, and package that. This would have provided code that worked, but which in many places bore no resemblance to what was in the book. Thus it would be useless to anyone following along after the Django 1.0 release, because although it worked, there would have been no explanation of why it worked or the mechanics behind the specific changes.

All around, this sucked. It sucked for people who wanted to simply follow the book. It sucked for people who wanted to try out the code. It sucked for Apress, who got a lot of complaints. It sucked for me, because it sucked for everybody else and I couldn’t really fix it.

This time around, I have an API-stability guarantee to build on, which means there will be a working code package. And to try to make up for how much the first edition sucked, I’m doing my best to make it a bit more useful than the typical book+code package. Here’s how it’s going to work: I have a private repository set up on Bitbucket (which is where all of my personal projects are hosted nowadays). As soon as I have the free time — hopefully this weekend — I’m going to sit down with a copy of the book and start working through the code. Each change and each new bit of code in the book is going to become a revision in the repository.

This will provide some (I think) useful features, including:

Easy problem tracking. Apress’ errata system works, I guess, but Bitbucket gives an issue tracker for free, so hopefully people will use it to point out any errors they find. Continuous errata; if bugs are found in the book’s code, I’ll push corrections to the repo and get a new package up. Lots and lots of metadata. I plan to use Mercurial tags to mark things like beginnings and ends of chapters, to make it easier to see the state of the code at particular points in the book. Packages of particular segments of the book. Bitbucket supports automatic packaged downloads of any tag in the repository, so if you want, say, a package of the code as it stands at the end of Chapter 5, you’ll be able to grab it. The ability to literally follow the book through the repository; if you want, you’ll be able to incrementally step through one revision at a time to match what’s going on in the book. Various extras, such as templates not covered in the book, will be present in the repository.

And, most importantly, it’ll be public. The code doesn’t contain any of the text or explanations in the book, so if you want that you’ll still have to get a copy, but anybody will be able to see the code for the applications described in the book. And since it all runs on current Django, it means that if you have a copy of the first edition you can probably compare to see what changed.

As soon as the repo’s up I’ll post a followup announcement and update this entry. Depending on time constraints, I may go ahead and open it before everything’s in there, but for now I’ll just have to see how much I can get done quickly.

Meanwhile, if you’re in Lawrence and you’re going to the LPDN cookout tonight, let me know and I’ll see about bringing a few copies of the book with me :)

Update, July 6: So running all the code into a repository without making any mistakes turns out to be tricky. I’ve managed to screw it up a couple times now, and started over yesterday with a fresh empty repo. The first three chapters are in, and I’ll try to get another chapter or two in tonight and then make it public. That means it won’t be complete right away (it’ll take me a little while longer to finish up), but people are apparently clamoring for code, so hopefully this’ll help.