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 <[email protected]> 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 > _______________________________________________ darcs-users mailing list [email protected] http://lists.osuosl.org/mailman/listinfo/darcs-users
