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.