[darcs-users] The future of darcs - glowing or gloomy

[Thorkil Naur]

Hello all darcs-users,

Here is a letter that I wrote to Eric, but I was a sissy and kept it private. 
You will get Eric's initial response, with his permission, in a moment.

Best regards
Thorkil

On Tuesday 03 March 2009 11:06, Thorkil Naur wrote:
> Dear Eric,
> 
> I am writing to you in private, not because any of what I would like to say 
> couldn't be posted publicly, but because I am going to voice some 
> disagreements with you that could lead to some discussion that one or both 
of 
> us would perhaps prefer to be conducted privately. For a while, I have had 
> some concerns about the future of darcs, the community and all those things. 
> The thing that eventually made me write the present letter is your response 
> "a newbies confusion with repositories - darcs or 
> git" (http://lists.osuosl.org/pipermail/darcs-users/2009-March/018024.html) 
> with its statement "darcs will always preserve user intent" - sorry, but 
this 
> is not true in any significant sense. And I believe that you actually would 
> agree with me in that. So what I don't really understand is, why you feel 
> that it is necessary to promote darcs using such inaccurate (to put it 
> nicely) statements.
> 
> A famous Danish shipowner once said "Speak the truth, it is so much easier 
to 
> remember" (paraphrased from the Danish original "Sig sandheden. Den er 
> lettest at huske") which is, of course, a somewhat blatant way of putting 
it. 
> But I seriously believe that confidence and trust in a product, such as 
> darcs, that performs a potentially critical task, and also confidence and 
> trust in the community that supports the product can only be built and 
> maintained if we are ruthlessly open and honest about everything, including 
> facts that may not be particularly flattering or convenient.
> 
> So this is, briefly, the background of this letter. In the rest of the 
letter, 
> I will bring out additional matters that have caused me to worry. In reading 
> this, please understand that I highly respect and value your efforts in the 
> darcs project. Quite simply, I doubt that darcs would exist for long without 
> you, in its present state. On the other hand, I sometimes miss, perhaps, a 
> somewhat firmer hand when dealing with certain types of issues. But read on 
> and judge for yourself. Or ignore, that's your option too, of course.
> 
> The famous patch theory: What is it that makes darcs tick?
> ----------------------------------------------------------
> 
> I dip into your reponse quoted above and find the statement "So darcs has a 
> clean theory which makes it possible to use a revision control system in a 
> new seamless way."
> 
> Honestly, this is not my impression. It could be that there really is such a 
> clean theory in somebody's head, but I, for one, have not been able to find 
> any trace of a comprehensive description of this theory. There are lots of 
> little pieces of something in many places. And there are many hints of 
things 
> being stated, on mailing lists and IRC-channels, about properties of the 
> original darcs 1 theory, the newer darcs 2 theory, the coming Camp theory 
and 
> all that.  But it seems risky to me, based on this meagre evidence, to 
> conclude that there really is such a theory with the assumed, desirable 
> properties.
> 
> I will hasten to add that this fact does not, in itself, detract from the 
> value or usefulness of darcs, but I do believe that darcs must be evaluated 
> in a much more down-to-earth manner. Briefly, I have no doubts that David 
> Roundy's ideas here are extremely interesting and useful and that he has 
> managed to express these ideas in the form of this wonderful program that 
can 
> perform many tasks better than comparable tools. With darcs 1, he got some 
of 
> the way and that, as we have seen, led to a program that was sufficiently 
> useful in practice for a number of projects (not least GHC) to adopt it. 
With 
> darcs 2, he (presumably) went somewhat further with this, leading to the 
> elimination of certain difficulties that haunted darcs 1.
> 
> Now, rather than leaning against some fancy theory here, I believe that we 
can 
> firmly attribute the usefulness of the original darcs to the brilliance of 
> David Roundy. But to claim that there must therefore be this theory that 
> explains the usefulness seems rash to me. Even David Roundy himself (in the 
> "Theory of Patches" appendix to the darcs manual, I am referring to the 
darcs 
> 1.0.8 version that I have printed and can therefore conveniently study) does 
> not appear to claim any such thing, writing, for example, in a footnote 
> "Alas, I don't know how to prove that [some important constraints] even 
*can* 
> be satisfied. The best I have been able to do is to believe that they can be 
> satisfied, and to be unable to find an [sic] case in which my implementation 
> fails to satisfy them." In this, I believe David Roundy perfectly expresses 
> what I believe to be the case: He has found significant and profound 
> inspiration in quantum mechanics (and I, as more of a matehematician, am 
> thinking in terms of the theory of non-commutative groups) and implemented 
> something based on that. But the result is that implementation, whatever 
> cleverness David Roundy has managed to put into it, no more, no less.
> 
> And where does this leave us? Essentially, at the mercy of David Roundy.  
> Although some initial attraction to darcs may be caused by the notion of the 
> theory of patches, in the long run, only experience with using darcs can 
> maintain this attraction.
> 
> And experience is needed: Darcs is a powerful, a sharp, tool. Inexperienced 
> hands will often be cut.  This is perhaps also part of the attraction of 
> darcs.
> 
> In any case, what worries me profoundly here is the apparent lack of 
> familiarity in the community with central parts of the darcs implementation, 
> probably what in some places is called the darcs core. As indicated, I do 
not 
> believe that we can lean against any patch theory, I would even go so far as 
> to claim that this theory doesn't really exist.  All we have is this 
> wonderful program, initially written by David Roundy.
> 
> On various occasions, I have had the opportunity to ask questions in the 
> community about the darcs handling of patches and other technical issues. 
And 
> I have followed discussions of these matters in the community. My impression 
> may certainly be wrong, nevertheless I believe that absolutely nobody in the 
> present community would be able to handle some fundamental difficulty with 
> the central patch handling code in darcs that may come up. This conclusion 
> is, admittedly, based on rather skimpy evidence. I try not to be too forward 
> in the way I communicate. But I clearly sense a lack of enthusiasm in the 
> community when the subject closes in on these central issues.
> 
> A few observations that may support this view are: (1) The lack of response 
to 
> Trent's very relevant observation of duplicated code in darcs "Duplication 
> between Prim and 
> 
Commute" (http://lists.osuosl.org/pipermail/darcs-users/2008-December/016633.html);  
> (2) The lack of relevant response to "Issue 1363 mark-conflicts says there 
> are none, but push says there are" (http://bugs.darcs.net/issue1363) which 
> could, as I see it, indicate some fundamental (although not necessarily 
> significant) problem with darcs 2.
> 
> Lack of familiarity in the community with the darcs core is, of course, 
> extremely serious in the long run.  I could be wrong, but if familiarity 
with 
> the darcs core is as thinly spread as I believe it to be, we should be much 
> more expressive about it and work towards increasing familiarity.  Exactly 
> how to do that is not clear, of course, but the problem needs first of all 
to 
> be acknowledged and perhaps even mapped in some detail.
> 
> The matter of the "borked CRC" (Issues 842, 844, and 1239)
> ----------------------------------------------------------
> 
> You recall this issue, I am sure, where invalid calls to zlib combined with 
> lack of error checking has produced a number of darcs repositories with CRC 
> errors in their patch files.  (At least, that's how I would summarize the 
> situation, it may be inaccurate.) What I am worried about here is the 
> apparent tendency of the community, when dealing with this issue, to cover 
up 
> the mess, rather than working seriously towards a fix.
> 
> Let me tell you first how I would react if I found that some routine error 
> checking had been left out in a program that I was responsible for and that, 
> furthermore, could be handling the crown jewels of my customers: I would 
> introduce the required error checking, unconditionally, in the working 
> version of my program. And if there were several versions (such as in this 
> case where several ways to link to zlib exist), I would introduce error 
> checking for all the versions. Furthermore, I would institute, at a very 
high 
> priority, a review of all the code, to find any additional cases of such 
lack 
> of care. And correct them.  And I would make sure that no further versions 
of 
> my program were released without these routine checks.
> 
> Only then would I take stock and consider my further moves. Most likely, my 
> program would now be in some more or less crippled state, not working 
> properly.  And the task ahead would be to fix that problem, including, of 
> course, taking care of the mess (in this case, repositories with CRC errors 
> in them) that has been created. But I would not accept the continued 
> existence of a circumstance (lack of routine error checking) that increased 
> the risk of my customers being hit by additional, independent, problems, 
> undetected.
> 
> Obviously, such a reaction could not be played out without my customers 
> noticing. And this could, of course, become somewhat unpleasant, having to 
> explain that you have made this glaring blunder and so on. But that's what I 
> would do, face the music, explain carefully and seriously the exact nature 
of 
> the problem, how it could be detected, its immediate resolution (stopping 
the 
> leak) and, as soon as possible, publish a repair.
> 
> Getting now to what has actually been done, the first problem is the 
unclarity 
> of the status of the problem and its resolution. Reviewing issues 842, 844 
> and 1239 (are there more?), I am struck first of all by the lack of an 
> explanation of what actually causes the symptoms that we see. I mean, we 
seem 
> to understand that an erroneous call (zero-length write) causes a CRC 
> computation error and we have observed that the gzclose error return is 
> ignored, but if there is any detailed description of the exact circumstances 
> that explains the symptoms that we have seen (including why we see the 
> problem for some darcs versions and not others), it is certainly not 
included 
> on the bug tracker. Some urgent questions that I lack answers to are:
> 
> 1. duncan.coutts observed that gzclose error returns were ignored, but the 
> matthias.andree investigations showed that gzwrite were called with a zero 
> length buffer (or something like that) and got a response from Vladimir 
> Nadvornik <nadvornik at novell.com> on the Novell BTS that indicates that darcs 
> is also ignoring error returns from its gzwrite calls. Has this been 
adressed 
> by anyone?
> 
> 2. The question has been raised, but no answer given, as to why darcs is 
> writing zero-length buffers at all. I am not at all saying that writing zero 
> length buffers is necessarily a bad thing: To maintain regularity of one's 
> code, writing zero-length buffers could be a perfectly sensible thing to do. 
> But the droundy patch to resolve this makes me worry again: If some part of 
> darcs is writing zero-length buffers, another part could be expecting to 
read 
> zero-length buffers. And if they are no longer being written, how will the 
> reader be told?  There could be several simple answers to this, but I have 
> not seen any.
> 
> A resolution plan were discussed at some point and communicated 
> (http://lists.osuosl.org/pipermail/darcs-users/2008-November/016276.html). 
> The plan calls for a period in which the missing routine error checking is 
> retained, and even error checking taken away in places where it had been 
> present earlier (through the use of the darcs C zlib bindings, I believe). 
As 
> you may guess from my earlier description, this seems taking a route that I 
> would certainly not risk in something that I was responsible for. In 
> addition, the eventual resolution seems to call for some fairly intricate 
> modifications to the external zlib bindings 
> (http://lists.osuosl.org/pipermail/darcs-users/2008-November/016363.html) 
> which would then presumably have to be combined with some, probably 
> non-trivial, modifications to the darcs code. The path is unclear here in 
> that no-one seems to have taken the responsibility of actually carrying out 
> these tasks.
> 
> There is also your own message to the darcs community about this 
> (http://lists.osuosl.org/pipermail/darcs-users/2008-November/016271.html). 
> This message, of course, takes much the same route as I would have taken by 
> openly explaining the problem, with the very significant exception that one 
> aspect of the problem (lack of error checking) is allowed to remain and even 
> expand indefinitely. And thereby putting our customers at risk.
> 
> So what is the point of this? You may very legitimately ask why I have not, 
> myself, as appointed Issue Manager, done something about this. And this is 
> fair enough, at least as far as ensuring that the bug tracker contains or at 
> least refers to the relevant discussion. As the January 2009 darcs release 
> approached, mornfall asked for a status update 
> (http://lists.osuosl.org/pipermail/darcs-users/2008-December/016799.html) 
and 
> as a result got some updates. If he had not done so, I would, but perhaps my 
> questions would have been a bit more pointed.
> 
> But my main frustration has been this rather fundamental disagreement with 
the 
> approach chosen to resolve the problem. And the lack of answers to certain 
> urgent questions, as noted earlier. I have voiced my opinion and asked 
> questions on #darcs a few times, but the reaction I got from there left 
> little doubt in my mind as to what people thought about this. And this is 
> where I believe we move into project policies rather than mere issue 
> management. And hence, calls for a kowey rather than a thorkilnaur.
> 
> The role of tests and documentation when working with darcs
> -----------------------------------------------------------
> 
> There has been some recent discussion of tests on the mailing list, the 
latest 
> is your summary 
> http://lists.osuosl.org/pipermail/darcs-users/2009-February/017838.html. I 
> would like to add "missing documentation" as a further sore spot to "missing 
> tests".  I am not sure about internal (primarily Haddock?) documentation, 
but 
> I certainly have the feeling that the external documentation, I mean the 
> darcs user's manual (the one I have printed in the 1.0.8 edition) and the 
> darcs --help texts are not being cared for sufficiently. I know that 
> certainly Trent has been doing a lot of work here, but still, I have the 
> impression that changes are allowed into darcs that modifies its behaviour, 
> as seen by the user, but without necessarily also changing the description, 
> also seen by the user, of that behaviour.
> 
> And here is another point where I have disagreed with what has happened: At 
> some point, some mechanism which was used to help keep (some of the) 
> documentation and code synchronized was removed, the code and documentation 
> separated and thereby allowed to diverge in peace. The argument for doing 
> this was that this complex mechanism would tend to scare off people who were 
> considering contributing to darcs. My priorities in such a matter would be 
> very different here.
> 
> At this point, we get into a more general discussion of how open source 
> communities work, and again I am afraid that I disagree with common wisdom 
in 
> such circles.
> 
> Let me take a statement by Duncan Coutts whom I am sure we both respect and 
> value highly: I don't recall the exact circumstances, nor have I managed to 
> find the exact spot (whether on some mailing list or IRC-channel), but it 
was 
> in a context discussing the level of documentation of Cabal.  Where Duncan 
> expressed the view that he much preferred working on fixing things and 
> writing new code rather than documenting code that is, perhaps, not entirely 
> in order. A point of view that one can easily understand.
> 
> However, when taking a slightly more high-level view, you have to face that 
> this code that is, perhaps, not entirely in order, nevertheless was entered 
> by someone in the first place. And that these someones got away with 
entering 
> it, without properly documenting it. We can recognize what happens in such 
> situations, this is perhaps just a minor detail that we don't expect to be 
> permanent, it is actually rather difficult to document nicely and so on. But 
> I believe that it is in exactly this situation where we should insist on 
> proper documentation. In fact, if some code cannot be properly documented, 
it 
> seems likely to be ill-conceived and, for that reason, it may be a good a 
> reason as any other to refuse it.
> 
> We may be scaring away developers with such a policy. On the other hand, I 
> firmly believe that if you evaluate work honestly, the mere code that 
> supports some new feature or corrects some problem only represents part of 
> the value of the work, accompanying tests and documentation also count 
> significantly. So there seems to be all the reasons in the world to take 
each 
> proposed change and, if not supported by tests and documentation changes, 
> return it to the sender, politely asking for something complete, rather than 
> something partial.
> 
> I don't believe that we are doing this at present, not very well at least. 
> What I fear might happen as a result of this is a steady decline in the 
> quality of our documentation: Not only are developers allowed to contribute 
> code without documentation, but people who may want to contribute 
> documentation are discouraged because whatever work they have done today may 
> become out-dated without notice by tomorrow's code change.
> 
> So, I am all in favor of strict requirements to darcs contributions: Both 
> tests and documentation should be included with code changes. Easier said 
> than done, I know. But if not said, it will not be done. And darcs will 
> wither.
> 
> Conclusion
> ----------
> 
> I am not sure what the conclusion here is. From my point of view, it has 
been 
> useful to express these things that I have had difficulties expressing 
> elsewhere, so thank you for reading as far as this. I don't have any 
> particular expectations as to what your response to this will be, but I hope 
> that you will find the insight that you get into how I look at things 
useful.
> 
> Best regards
> Thorkil
>