[darcs-users] Theory of Patches

[Eric Kow]

On Fri, Apr 10, 2009 at 01:37:35 +0200, Daniel Carrera wrote:
>> In particular, I suggest adding yourself to
>>   http://wiki.darcs.net/index.html/PatchTheoryPeople
>> at some point to help grow the patch theory community
>
> Me? I'm just a newbie.

Newbieness is useful.  It keeps us honest.

> I see. I guess the resources are very scattered. There's the Darcs wiki,  
> Camp, the darcs manual and the wiki book. :-(

Yep.  My take on it:

- the darcs manual is official but old, and missing discussion on darcs 2
- the darcs wiki is broad, but shallow
- the wikibook tries to be friendly, but isn't rigorous and probably
  gets on people's nerves.  Plus it's horribly incomplete
- the camp documentation is new and quite thorough (although it doesn't
  explicitly cover darcs 2)
- Jason's thesis is clear and introduces the patch theory stuff, but it
  doesn't go into that much detail

> I don't want to make any commitment, but with that understanding, sure.  
> I'm generally good at writing/organising technical documentation. I just  
> have too much work to make any commitment. But if you can accept  
> sporadic, random, unpredictable help, sure.

We can accept any help.

Trent Buck has been our de-facto documentation manager (he says not
ready to make formal commitment yet, but he's been thinking about this
stuff the most), so it might be good to coordinate with him.

> For starters, where would you like to see the patch theory stuff to be?  
> Darcs wiki? Camp? Wikibooks?

Short answer: the manual

Long answer:

I believe there are two kinds of work to be done: The first is to cut
down on the proliferation of incomplete resources.  This could consist
of a lot of pruning bits off everything (for example, recognising that
some chapters in the wikibook might never be written, and just pointing
them to an official source instead), or just marking discussions as
being old and obsolete as needed.

The second is to flesh out the documentation we have, and this I believe
should take place in the darcs user manual.  I would love to see this
stuff refreshed, for example with modernised notation from Jason's
thesis and maybe camp stuff, unified terminology, and the darcs-1 stuff
clearly delineated from the darcs-2 stuff.

For example, it could start with an overview of patch theory
(commutation and merging), and then move on to conflicts and say: here's
how we dealt with conflicts in darcs 1, here's how we do it in darcs 2
(the idea being that in the future, we could tack on the camp stuff).
I'm not sure what is the right way to go about this. Maybe it could
consist of a great merge, pulling in bits and pieces from the newer
write-ups like Jason's thesis and newer work like Ian's paper (which
does not explicitly describe darcs-2 but covers a lot of the same
ground, which sadly the darcs manual does not seem to).

The dream is for somebody else to be able to come up and ask "where can
I learn about patch theory", and we can point them to the One True
Source.

I hope I'm not making this sound like too daunting a task!  If this kind
of shake down is too hard, there is still a lot of on-and-off gardening
we need doing.  I'm just trying to sketch one of my patch theory dreams
out and hope that somebody else can up with a plan.  What do you think?

-- 
Eric Kow <http://www.nltg.brighton.ac.uk/home/Eric.Kow>
PGP Key ID: 08AC04F9
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 194 bytes
Desc: not available
URL: <http://lists.osuosl.org/pipermail/darcs-users/attachments/20090410/a6839c61/attachment-0001.pgp>