Anarki updated to arc3

Note for regular readers (if I have any): this post is specific to the Arc community and probably incomprehensible to anyone outside it.

Overview

So after much dithering on my part about how to handle the update to arc3, and especially regarding how to cleanly incorporate CatDancer's ideas about sharing hacks, I've decided to forget about all that difficult stuff and just use the old model. More on the reasons for that below, but first, what I've done to anarki.

The old arc2-based master, stable, and hygiene branches of anarki have been renamed arc2.master, arc2.stable, and arc2.hygiene respectively. The new master and stable branches are based on arc3.1. However, in case you haven't been following along until now, they are not simply the merge of the arc2-based branches with the changes made to reach arc3.1. I determined that a complete or even partial rewrite of the arc2-based anarki code would be too difficult; again, see below for rationale.

Instead, they have entirely new development histories based on the official branch (currently at arc3.1.tar). I've hand-ported the features I most liked from arc2-based anarki, with some important changes, intended to reduce cruft in the long run so that porting to arc4.tar, when it comes, won't be such a pain in the ass.

Unfortunately, this means that updating to the new anarki is not as simple as just git pull, because merging your local master and stable with anarki's updated branches would be disastrous. I'll repeat this, because it's important: do not simply pull from anarki as you have done before. It will not work.

In fact, the easiest way to handle the update is to just git clone a fresh copy of git@github.com:nex3/arc.git. Then, if you have any work in your old local repo you want to transfer, do so by hand. However, for those who don't wish to do this, explanation follows.

Updating without cloning a new repo

Assuming you don't have any unpushed commits or changes you don't care to lose on your master and stable branches, then the following should "just work":

$ git pull origin +master:master +stable:stable

If by chance you're also tracking my hygiene branch, add +hygiene:hygiene to the end of that command. If you're not tracking the stable branch, remove +stable:stable.

For those interested, this command tells git to pull the master and stable branches from the origin remote (anarki) into the correspondingly-named local branches; the + at the beginning of the refspecs indicates that the local branches should be forcibly updated, ignoring the fact that they have a different version history from their remote versions (that, in git parlance, the update is not a "fast-forward").

If you do have unsaved work you want to keep, then instead you'll have to rename your branches:

$ git branch -m master arc2.master
$ git branch -m stable arc2.stable # only if you track the stable branch
$ git branch -m hygiene arc2.hygiene # only if you track the hygiene branch

After this, update your .git/config file to change what remote branches they're tracking:

...
[branch "arc2.master"]
        remote = origin
        # merge = refs/heads/master # BEFORE
        merge = refs/heads/arc2.master # AFTER
...
[branch "arc2.stable"]
        remote = origin
        # merge = refs/heads/stable # BEFORE
        merge = refs/heads/arc2.stable # AFTER
...
[branch "arc2.hygiene"]
        remote = origin
        # merge = refs/heads/hygiene # BEFORE
        merge = refs/heads/arc2.hygiene # AFTER
...

After you've done this, it's safe to git pull from any of the branches. However, you won't yet have any of the remote arc3-based branches. To fix this:

$ git fetch
$ git branch -t master origin/master
$ git branch -t stable origin/stable

Why not just merge pg's changes into anarki as it was?

The changes between arc2.tar and arc3.tar are many and significant. The changes between arc2.tar and anarki's core files are even more numerous. Merging these two sets of sometimes wildly divergent changes correctly is a task beyond me. Even were this accomplished, much of the non-essential code on anarki (libraries, etc.) would need updating. While in most cases updating to arc3 might be simple, the sheer volume and variety of code prohibits it being done by any one person; whereas leaving a pile of crufty nonworking code around is, first, horribly confusing to any newcomer who wants to get acquainted with what anarki has to offer, and second, aesthetically unpleasing (to say the least).

So instead I've made a clean start. Instead of porting arc2-anarki wholesale, I've forward-ported the features I myself most wanted, and I encourage everyone else to do the same. That way, we'll end up (eventually) with all the features of arc2-anarki that people actually used, and none of the dead weight.

Speaking of which, this new start provides a perfect opportunity to cull some of the cruft that infested arc2-anarki. In particular, I'm thinking of the things that made porting anarki to arc3 so difficult: lots of changes to core files, little documentation of added features, and poor separation of the code that adds features. Read on for more information on this last point.

Ported and changed features from arc2 anarki

The most significant things I've written for and ported to arc3-anarki are an improved $ special form, programmable coercion, anarki's old interactive help system (help, fns, etc), and an improved version of anarki's extended [] syntax.

This last one provides an opportunity to showcase another thing I've added: a CHANGES/ directory. Arc2-anarki made a lot of extensions to arc, but most of those features can only be discovered by looking through the source code — a time-waster even for an experienced arc hacker, and simply not workable for a newcomer — or reading the posts people make about them in the forum — a good way to keep up on new developments, but not so good for discovering long-established hacks. So, in future, I encourage other anarki hackers to document their changes by creating a file in the CHANGES/ directory; and as an example, I'll point you to the documentation for the new [] syntax.

I've also added another directory, load/. All .arc files in this directory are auto-loaded by libs.arc when arc is started up. The intention here is that, instead of putting useful language additions like help and require into, say, arc.arc, you can add a file in load/ which defines them. This avoids "polluting" core arc files, reducing the difference between arc.arc in anarki as compared with arc.arc from arcn.tar; and like CHANGES/, it makes feature discovery easier for a newcomer.

Addendum: what about CatDancer's "hacks" model?

In brief: too difficult to scale manually, couldn't find a good tool, implementing it in git pollutes the version history with a lot of merges, and ultimately extracting the hacks myself was easier than trying to maintain them independently.

TODO.