[darcs-users] the adventure branch
kowey at darcs.net
Sun Aug 29 12:16:19 UTC 2010
Thanks again to Petr and Jason for opening this discussion on the
proposed adventure branch. For those who want to get up to speed
quickly, I hope to keep a summary of the proposal at
This is the first of two replies. In this mail, I'd like to address
what I think are the core issues behind the thread. In a follow-up
message, I'd like to make some remarks about style and tone.
Let's get to work. I think it's important that we keep the context
behind the adventure branch in mind: Between mid-September and
mid-January, Petr will have a good chunk of free time on his hands, time
that he would like to spend working on Darcs. We want find the most
effective use of this time: both for Petr (more time hacking, less time
dealing with crap) and the Darcs project as a whole (better quality
code). This leaves us with two questions:
1. How do we review work from a single developer who is spending
disproportionately more time on the project than the others?
2. How do we convince ourselves that the work is correct?
I hope we can make progress on both fronts. These questions are
important partly because of the kind of work we want to do may involve
some invasive changes and aggressive refactoring.
1. Review logistics
I think we all agree that the Darcs code needs a lot of cleaning up,
which may involve some large, sweeping changes to the code. And before
there is any more misunderstanding, nobody ever said anything about
rewriting from scratch -- there's no need for this discussion to go into
the pros and cons about rewriting from scratch because that's simply not
on the table. So no rewriting from scratch, but a lot of heavy hacking.
We also agree that code review is important to us, not so much for
catching bugs but for building a shared understanding of the Darcs
code. If code review is going to work, it's going to need to happen
incrementally: the chunks have to be small enough for reviewers can
understand them in time available.
There's a tension between our desires for aggressive changes and
incrementality. On the one hand, we want to do this big chunk of work,
deep and wide-reaching as it may be; but on the other hand, we want to
do them in a way that doesn't meltdown the current review
infrastructure. If Petr and perhaps other adventurers are going to be
cranking out patches, how is the rest of the Darcs team going to keep up
in reviewing these changes? Moreover, the wide-reaching changes that
Petr proposes may involve certain "work in progress" stages that break
Darcs along the way. Do we sit and wait for one big finished product?
Or do we accept the work in a more incremental fashion, bugs, warts and
The adventure branch proposal provides more of a compromise between
aggressiveness (fork) and incrementality (status quo). We still insist
on regular team-based reviews because we think it's important for us to
understand the code as it evolves, but we soften the review process to
keep it practical. I want to make it very clear that the proposal isn't
really about any one developer. It's mostly about the unique situation
where we have both asymmetrical free time and a lot of aggressive
refactoring to do. This sort of thing could happen again and we need to
learn how to cope gracefully with such a bounty.
Now, the proposal isn't perfect. First, some details may still be
underspecified. I think we should update the wiki page  saying what
work we plan to do on the branch, when we consider the branch to be
successful and perhaps what sort of quality assurance guarantees we will
aim for. Second, one worrying logistical point that Jason brought up is
that such a branch could mean the Review Team has to split their
attention between two different parallel on-going branches of
development, which could be detrimental to small volunteer team like
Darcs. But in a sense, we're already dividing our attention between two
branches of development (the mainline and the current release branch for
2.5), each with their own set of rules. It's not great, but we seem to
be coping. Nevertheless, this could be a problem worth paying attention
That said, the adventure branch remains the most viable proposal we have
so far for tackling the aggressiveness/incrementality tradeoff. But
does anybody have another idea? Perhaps there is a more creative
solution that nobody has considered yet. Overall, how do we make this
Assuming we get our review logistics under control, we also need to pay
attention to the problem of correctness that Jason highlights. Suppose
we follow the Adventure Branch approach to doing the work. One thing
the proposal has not made clear is: when is it safe to flip the switch?
How will we determine that the experiment has been successful and that
it is safe to merge the branch back into the mainline?
It would be extremely useful for us to agree as a team what our
conditions of success are. Following Jason, we can think of the current
test suite as a sort of weak baseline, but given the nature of the
changes, perhaps we can do a lot better. His point is that our
Quality Assurance should have a rigour that is commensurate with the
invasiveness of our changes. Look, we want to strap a jetpack onto Petr
so he can go really really fast, right? All Jason is really saying is
that with great Jetpack comes great Crash Helmet.
Now if you ask me, formal proofs may be a lot to ask for and writing
bits of Darcs in Agda isn't going to happen for a while. Moreover,
simply demanding some kind of great Cultural Shift isn't going to have
much more effect than alienating Darcs developers who are already
hard at work and struggling to keep up with current demands. I've
banged on my fair share of drums, but I know that drum-banging alone
is not how we make progress. Still, the overall point that we need
to put Quality Assurance first is fairly reasonable, and we should
Maybe this chunk of time is a chance for us to experiment with some
extra testing discipline, perhaps by requiring a QuickCheck for every
new function we export in the great refactor. Not feasible? OK, well
maybe there's something else we can negotiate for. I would love to see
some sort of agreement on what level of extra evidence would be
reasonable to ask of the Adventure Branch.
I certainly do not want to impede the kind of work that Petr has in
mind; I agree that he should be able to move swiftly. But think, for
example, about the NewSet work for Darcs 2.5. NewSet is a great piece
of work and it seems to have made Darcs a lot more solid instead of just
faster. But we kept discovering these bugs during the betas, mostly
through dogfood tasting (eg., issue1865, issue1873, issue1888). Yuck!
So that's a lot of debugging effort we've spent. Could we have avoided
it with a more proactive approach?
We have two problems to solve: making it practical to do the kind of
heavy cleanups we want in the time allotted, and making sure the results
are correct. I hope we we will find a way to get the best results we
can from this adventure. Can we make it work?
PS: Thanks to Jason, Petr and Ganesh for your feedback on drafts
of this letter. Keep in mind that we all have different takes on
this issue, and the opinions (and interpretations) expressed in this
letter are mine and not theirs.
Eric Kow <http://www.nltg.brighton.ac.uk/home/Eric.Kow>
For a faster response, try +44 (0)1273 64 2905 or
xmpp:kowey at jabber.fr (Jabber or Google Talk only)
More information about the darcs-users