RnRS Gardening

HomeAbout

Monet's garden at Giverny

Mon 8 Apr 2019
scheme

As long as the roots are not severed, all is well. And all will be well in the garden.

— Chance the Gardener

Programming language communities are like gardens. Often, we get to grow something new and beautiful. But sometimes, we have to collect our tools and do grunt work just to keep things alive. This is a story about recent grunt work on two web sites in the garden of Scheme. I learned a few lessons in the process.

small.r7rs.org

First, some background: The most recent round of Scheme standardization, known as R7RS, divided the language into two versions, Small and Large. In 2013, after several years of work, working group 1 finished the specification for R7RS Small, and it was approved. Now, working group 2, chaired by John Cowan, is working on R7RS Large. (This is all being done by volunteers, and you're welcome to participate.)

For our work on R7RS Small, WG1 used Trac, an open-source issue tracker and wiki, at the domain trac.sacrideo.us. In late 2018, the site was taken down because the hosting provider stopped supporting it. Fortunately, we had backups. John restored the wiki pages from a recent backup, then did a rough translation of each page's markup into HTML or Markdown. Those pages are now hosted by Bitbucket, and r7rs.org points to them. John continues to update those pages as part of his work leading R7RS Large.

So we had our wiki pages again. However, the Bitbucket site doesn't include any of the issue-tracking pages that WG1 used to track a total of 538 tickets covering topics like Make nested quasiquotes work properly and Extend finite? and nan? to non-real values. Also, since it's a living site, it doesn't represent a historical record of what went into R7RS Small. R7RS Small was a big effort, and the Scheme community has a long tradition of doing its work in the open, so it seemed important to preserve that work somehow.

However, none of us wanted to run a Trac site. For my part, I wasn't interested in installing Trac, keeping up with security updates, and expanding the attack surface of my personal web server in the process. Faced with this dilemma, I procrastinated for months, then did something that's normally a bad idea. I implemented, in Scheme, a nearly complete implementation of Trac's elaborate markup language (WikiFormatting) as well as a good part of its data model. Using that code, I generated a replica, as static HTML files, of our Trac site. That replica is now hosted, thanks to Jonathan Rees's DNS wizardy, at small.r7rs.org.

Reimplementing a system from scratch is generally not advisable. It almost always turns out to be a bigger project than planned. Getting all the corner cases right, and matching the detailed behavior of the existing system, which has benefited from the work of many contributors over years, is a big job. On the other hand, in this particular case, I only had to get it working well enough to match one set of input data, and that data would not change, since it was a historical record. The maintenance, performance, and security benefits of serving a static set of HTML files instead of running a Trac instance were just too good to pass up. And implementing WikiFormatting was a self-contained programming challenge with a quick feedback loop, so it was fun to work on.

Every page on small.r7rs.org has a banner at the top explaining that it comes from a static snapshot of our Trac instance. Any page that John and I thought might possibly have been updated as part of the R7RS Large work has a link to the Bitbucket version, too. And all pages have links to their source in case I've screwed up the formatting somehow in my translation. Both wiki pages and tickets have been preserved.

Thanks to Aaron Hsu, requests to the old trac.sacrideo.us are now forwarded to small.r7rs.org, which rewrites the URLs to match the new URL syntax. As a result, as far as I could manage, all links to the old pages still work. (Right now, I'm using HTTP 302 Found, i.e. temporary redirects, but if all goes well, I'll eventually switch to 301 Moved Permanently.)

scheme-reports.org

At the scheme-reports.org web site, the official home of the Scheme reports, more bit rot had set in. Sometime around 2016, the scheme-reports@scheme-reports.org mailing list, which was the place for discussion of all the RnRS standards, went down. Not only did mail serving stop, but the entire archive of messages to the mailing list was lost. No backups could be found. However, Jonathan has managed to recreate the archive by extracting scheme-reports messages from his personal email archive and feeding them to MHonArc. Unfortunately, we haven't been able to reproduce the old URLs, so old URLs will now break. We've added a landing page that explains the history of the new archive so that people understand why there might be discrepancies or broken links. Mailing list delivery has been restarted, but new messages are not automatically pushed to the archive. (Maybe someday.)

We've gone through all the links on scheme-reports.org pages and updated them to account for the new email archive, the new small.r7rs.org site, and the latest URLs for the various RnRS reports, including all the R7RS Small drafts, errata, overview, etc.

Lessons

I learned a few lessons from these projects:

  1. In many cases, reimplementing software is a bad idea. But not always. In this case, making the investment now in exchange for future simplicity was a good tradeoff.
  2. Always own the domain name. In this case, we got lucky because Aaron owned the domain, but it would have been even better to have started with r7rs.org. Then we wouldn't have to maintain redirects across domains, and our URLs wouldn't be vulnerable to either of two sites going down.
  3. Always make backups and check that they work. We were lucky to have them for trac.sacrideo.us, but we didn't have them for the scheme-reports mailing list.
  4. Be careful when choosing a piece of software as a platform. It's easy to become committed to a piece of software by accident, and disentangling oneself from it may be a lot of work. It may be practically impossible. We were lucky to be able to replace Trac, but keeping the old Pipermail URLs proved to be too much to do.
  5. There are fun projects to work on even when doing grunt work.

Acknowledgements

Many thanks to Aaron, John, and Jonathan for all their help on these two projects and for their contributions to the Scheme community. Thanks, too, to Alex Shinn, chair of WG1, and to the members of the Scheme Steering Committee. And thanks to the authors and maintainers of Trac, which was a great asset while we were working on R7RS Small.