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.
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
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
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.)
At the scheme-reports.org web site, the official home of the Scheme reports, more bit rot had
set in. Sometime around 2016, the
firstname.lastname@example.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
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.
I learned a few lessons from these projects:
- 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.
- 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
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.
- Always make backups and check that they work. We were lucky to have
trac.sacrideo.us, but we didn't have them for the
- 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.
- There are fun projects to work on even when doing grunt work.
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.