So, the repository for the second edition of Practical Django Projects is not yet done, but due to the general clamor I’m opening up public access; you can browse it, or check out a copy of the code, from its page on Bitbucket. You’ll probably want to have a look over the README file displayed on that page, since it provides helpful information on how the repository works.
Right now the first three chapters’ worth of code (covering the first project in the book — a very simple content-management system) are in the repository; the rest is in the process of being added, and will likely come in spurts as I push bunches of commits from my local copy up to the public repository. But before I push any more commits I’d like to take a moment to explain the workflow I’m using for this, since it’s both mildly interesting and somewhat helpful in understanding the time involved in getting this to work properly.
The repository you see on Bitbucket right now says it was created a little less than two days ago. And it was, but also it wasn’t. The first attempt at this repository was created last year, when I started writing the second edition of the book. The thinking was that this would provide the eventual model for the public repository, but that during the writing process it would be useful for doing tech review. But that fizzled out, and for a while it wasn’t updated; it ended up containing a fun mishmash of corrections and backtracking edits that did more harm to its utility than good.
So as soon as I had a copy of the printed book in my hands — my first definitive copy of the text to work from, since there were a few changes still to be made to the book’s content even on the final proofs — I deleted the repository and re-created it, and started going through the book, following the general plan I’d laid out: each code listing in the book would be a changeset in the repository, and readers would be able to step through the repository one change at a time as they went through the book. Once all the code was in, I’d add a bunch of tags to the repository to mark things like where chapters begin and end.
And all was well for a little while until I noticed that I’d made a mistake in one of the early changesets and pushed it into the copy of the repository on Bitbucket. Crap.
Being a stickler and a perfectionist, I once again dropped the repository and started over, this time from just before the spot where I’d screwed up. And all was well for a little while until I did it again.
So on Sunday, I dropped and re-created the repository again, and started it over from scratch with a new workflow:
The advantage of this is that I’m free to screw up as much as I need to; if I do, I blow away the local Repository B, and re-clone from Repository A at a point before the mistake. And if a problem does creep into Repository A, I’m still doing another round of testing to try to catch it before it becomes public; in that case I blow away both repositories, re-clone from Bitbucket and try again.
The disadvantage of this is that it’s a timesink. Taking all of the testing and repository shuffling into account, each changeset can end up representing ten minutes’ worth of work or more (especially if I find an error; larger gaps between commits on the public history usually happen because of this). I pushed just shy of twenty commits tonight, for example, and it shows up as three hours on the timeline, or roughly nine minutes per changeset. Oh, and these are from the easy, beginner portion of the book. Some of the later stuff’s going to be really fun.
But I’ve finally got a workflow that lets me keep a clean history in the public repository while still being able to correct mistakes, and that’s what counts.
I do realize that certain other version-control tools would let me reach back and just edit history to suit whatever I’d like it to be, but I’m also quite heavily committed to Mercurial at this point; not being able to edit history, though it requires contortions at times, is generally a good thing (as is the overall simplicity of working with Mercurial). And I do realize that I could get the same effect in Mercurial with a patch queue, but that’s a much bigger can of worms than I’d care to deal with right now.
Anyway, that’s what’s up right now. Three chapters’ worth of code so far, all tested against current Django trunk, with more on the way. For those who desire it, a feed of commits to the repository is available, so you can track it in real time.
Meanwhile, I think the overall effect of this approach ends up looking rather nice. If somebody can come up with a way to make it easier to manage, I’d love for this to become a usual thing for technical books to publish code.
Comments for this entry are closed. If you'd like to share your thoughts on this entry with me, please contact me directly.
Hey James,
Good to hear you’re making progress on this. Something that might help you, from MQ (without the giant can of worms that comes with it), is ‘strip’, which will basically peel off revisions from the top. Say you commit, and then regret it, you can strip it by doing “hg strip tip”.
As you know, there’s much more magic in MQ that could/would help you, but I understand how it’s a daunting subject to throw yourself at, at this point.
Hi,James!
When are you planning to cover all chapters. Your writing style is so easy to understand that I’m moving through the chapters with light speed:). Thank you for your work.
I recently moved satchmo to bitbucket as well. I found that I had to use a similar workflow. I created a satchmo-gold and a satchmo-working repo and use that approach to manage pushing to bitbucket. It does introduce some extra overhead but the upsides are worth it.
Thanks again for the update to the book. Mine arrived last week so I’m making my way through it.
Amazing how the choice of DVCS and its “minor” features affects the workflow. If you have to stick to Hg you have to tough it out – there is no other choice available.
Brill - thanks :)
Hi, I’m learning Mercurial and I’m really impressed. It’s miles ahead of Subversion and it’s easier to learn comparing to GIT. I tried also Bitbucket which is an excellent service. I think Django development itself could migrate soon to Mercurial, on Google Code or Bitbucket. As for your book, I’ve just ordered a copy on Amazon (I didn’t purchased the first edition).
I think you’d find that MQ would help a great deal here. It allows you to move forward and back through your patch queue. You can finalize all the queued patches at the very end of the process.
It’s also possible to export your existing changesets as patches and load them into MQ.
Also; Django should switch to Hg. =)
Any movement on the the code downloads yet? Also, do you have any errata to post yet? I’ve already found several (including a show stopper on page 111 with the code to display and link the tags in the sidebar being completely busted), but haven’t had good luck in the past with Apress and submitting errata.
I hope this doesn’t turn out like last time without any code downloads or errata. I was pretty frustrated last time. Hope it’s going better this time. Thanks for the great book.
IMHO: time to learn about rebase. instead of deleting the whole history, delete (or change) just the broken commit. problem solved.
Hi, I am waiting too for the full version of the code. I must say a simple tar ball at the release of the book would have been enough for me. Furthermore, I guess you must have this hidden somewhere. Great book anyway, I have already learnt quite a bunch of new tricks, and I only have read half the book.
And now :
a small markdown test