How to demolish your software project with style

I did something unusual today. I pulled the plug on one of my own projects.

In Solving the CVS-lifting problem and Announcing cvs-fast-export I described how I accidentally ended up maintaining two different CVS-to-something-else exporters.

I finally got enough round tuits to put together two-thirds of the head-to-head comparison I’ve been meaning to do – that is, compare the import-stream output of cvs-fast-export to that of cvsps to see how they rate against each other. I wrote both git-stream output stages, so this was really a comparison of the analysis engines.

I wasn’t surprised which program did a better job; I’ve read and modified both pieces of code, after all. Keith Packard’s analysis engine, in cvs-fast-export, is noticeably more elegant and craftsmanlike than the equivalent in cvsps. (Well, duh. Yeah, that Keith Packard, the co-architect of X.)

What did surprise me was the magnitude of the quality difference once I could actually compare them head-to-head. Bletch. Turns out it’s not a case of a good job versus mildly flaky, but of good job versus suckage.

The comparison, and what I discovered when I tried to patch cvsps to behave less badly, was so damning that I did something I don’t remember ever having felt the need to do before. I shot one of my own projects through the head.

The wrong thing to do in this situation is to just let the bad code hang out there in the noosphere gradually bitrotting, with no maintainence and warnings to people who might stumble over it and think it’s safe to use or salvageable. This is bad for the same reasons abandoning a physical building and letting it decay into a public hazard is bad,

Instead, I shipped a final archival release with an end-of-life notice, prominent warnings in the documentations about the Bad Things that are likely to happen if you try to use it, and a pointer to a better alternative.

This is the right thing to do. The responsible thing. Which I’m making a point of since I’ve too often seen people fall into doing the wrong thing – usually through embarrassment at the prospect of admitting that they made a mistake or, possibly, can’t meet the qualifications to finish what they started.

I’ll say it straight up: I tried hard, but I can’t fix cvsps. Peeling away the shims and kluges and junk just reveals more shims and kluges and junk. Well, in the repo-analysis code, anyway; there’s another piece, a partial CVS client for fetching metadata out of remote CVS repositories, that is rather good. It’s why I kept trying to salvage the whole mess for about ten months longer than I should have.

What I think happened here is that the original author of cvsps did a fast, sloppy ad-hoc job that worked well enough for simple cases but never matured because he didn’t encounter the less simple ones. Keith, on the other hand, did what I would do in like circumstances – thought the problem entirely through on an algorithmic level and nuked it flat. His code is solid.

One of the differences that makes is that Keith’s code copes better when put under unanticipated stress, such as me coming along and sawing off the entire git-aware output back end to replace it with a stream-file emitter. But I digress. I’m not here today to talk about architecture, but about how to demolish your project with style.

Software is communication to other human beings as much, or more so, than it is communication to computers. As an open-source hacker, you are part of a craft community with a past and a future. If you care about your craft and your community, the end of a project leaves you with a duty to clean up after it so that it becomes a positive lesson to those who come after you, rather than a trap and attractive nuisance.

And now I’ll get off my soapbox and go back to work. On cvs-fast-export. After this, making sure it has a really good test suite before I ship 1.0 seems even more important.

16 comments

  1. Also got the malware warning. It looks like the warning is for all of ibiblio.org, not just this sub-domain.

  2. Sometimes there is another option, if there is superior alternative, namely adding to the alternative ability to emulate deprecated project. This is sometimes used even if neither alternative is dying, e.g. ispell emulation mode in aspell.

    In Git project there were two compering solutions to generate line-wise history of a file: git-annotate (name after “cvs annotate”) and git-blame (named after “svn blame”). git-blame turned out to be superior and better maintained, so nowadays git-annotate is “thin wrapper” around git-blame selecting alternate output format (sometimes massaging options would be required, translating commandline parameters, but not in this case).

    I wonder if cvs-fast-export could provide cvsps shim… there are quite a few projects that depend on cvsps; I’m not sure but git-cvsimport might be one (cvs-fast-export + git-fast-import is not incremental AFAIK).

  3. Looks like the malware problem has been solved. I got it when I first went to ‘read more’, but now the link is working properly. Not sure if having visited the page via an older email did anything, but it’s working fine now.

  4. Chrome Version 31.0.1650.63 reports malware :

    Safe Browsing
    Diagnostic page for ibiblio.org

    What is the current listing status for ibiblio.org?
    Site is listed as suspicious – visiting this web site may harm your computer.

    Part of this site was listed for suspicious activity 35 time(s) over the past 90 days.

    What happened when Google visited this site?
    Of the 400 pages we tested on the site over the past 90 days, 104 page(s) resulted in malicious software being downloaded and installed without user consent. The last time Google visited this site was on 2013-12-12, and the last time suspicious content was found on this site was on 2013-12-11.
    Malicious software includes 4 trojan(s), 1 worm(s).

    Malicious software is hosted on 2 domain(s), including yestblock.com/, operaget.pp.ua/.

    1 domain(s) appear to be functioning as intermediaries for distributing malware to visitors of this site, including operaget.pp.ua/.

    This site was hosted on 1 network(s) including AS36850 (UNC-CH).

    Has this site acted as an intermediary resulting in further distribution of malware?
    Over the past 90 days, ibiblio.org appeared to function as an intermediary for the infection of 7 site(s) including unc.edu/, gpgpu.com/, lexisweb.com/.

    Has this site hosted malware?
    Yes, this site has hosted malicious software over the past 90 days. It infected 0 domain(s), including .

    How did this happen?
    In some cases, third parties can add malicious code to legitimate sites, which would cause us to show the warning message.

  5. Eric, you have added deprecation warning to documentation (including cvsps(1) manpage), homepage and Freecode index, but forgot to update description on Gitorious.

    Nb. SourceForge has old version of CVSps (before maintainer change).

    1. >Nb. SourceForge has old version of CVSps (before maintainer change).

      Yeah, I know. I wish it wasn’t. The bugs in that version are worse…

    1. >Can the good metadata fetcher be added to cvs-fast-export?

      I knew someone would ask that. And the answer is: if it could be done, I’d have done it already.

      The problem is this: cvsps could parse cvs rlogs, which can be fetched via the CVS protocol, which cvsps knows part of. It emulates just enough of client-side CVS to do its job. But rlogs aren’t good enough for cvs-fast-export; it wants to parse the actual master files.

      I’ve looked in the rather incomplete and crappy documentation that exists for that protocol, hoping to find a request that fetches masters. If such a request existed, I could almost certainly modify the exiting protocol code from cvsps to use it, saw that part off, and graft it onto cvs-fast-export.

      Alas, it appears that no such request exists. So much for that nice idea.

    1. >Well, there is cvssuck; perhaps it could be used together with cvs-fast-export?

      Also a nice theory. Unfortunately, the one time I tried to use cvssuck it failed to work in a particularly annoying way. It replicated the directory structure of the repo but didn’t fetch any of the actual master files.

      The cvssuck code appears to be seriously bitrotted. And the home page has disappeared. No help in that direction.

  6. General approval for including the pointer to the superior alternative. A perennial gripe I have with older OSS software that hasn’t been updated in a while, is not knowing whether that’s because the project is feature-complete and hasn’t needed much maintenance, or because the project is obsolete and everyone moved to a better alternative. These two things often look the same.

Leave a Reply to Jakub Narebski Cancel reply

Your email address will not be published. Required fields are marked *