In the meantime, as always, you can follow @mechanical_fish on Twitter or even the mechanical_fish comment stream on Hacker News.

As I work to develop my testing chops it’s hard to avoid pining for Ruby, where the community has been obsessed with testing for years, where lots of experiments have been tried, and where the language syntax actually works with you to make test code more elegant. Even something basic, like asserting the presence of an exception in PHP:

1
2
3
4
5
6
7
8
9

<?php
$threw = FALSE;
try {
    something_broken();
}
catch (MyKindOfException $e) {
   $threw = TRUE;
}
$this->assertTrue($threw);

…becomes so much nicer in Ruby test/unit (which is hardly the last word in Ruby testing utilities):

1
2
3

assert_raise MyKindOfError do
    something_broken()
end

But, though we can’t hope to mimic the elegance of Ruby’s block syntax in PHP, we can at least try to take advantage of the Ruby community’s hard-won experience with testing methodologies and design patterns. One of my favorite Ruby bloggers was Jay Fields – he’s been working more in Java lately, but his old Rails links live on:

• First, the disclaimer: Even the “industry experts” on testing are still trying to figure it out, and there is no silver bullet: the right kind of testing to do depends on what you’re trying to write.

• Having said that: Setup and teardown methods make your tests less readable and maintainable, and the guy who designed the NUnit library wishes he hadn’t supported them at all.

• The Rails community has experimented with many ways of representing the data that your tests will operate on. Rails 1.0 provided fixtures; after much trial and error, the consensus seems to be that they suck and that you will eventually figure that out. The folks I follow have dabbled with Object Mothers before settling (for the moment) on the Test Data Builders pattern; the fairly popular Factory Girl library appears to be a Rails implementation of the Test Data Builder concept.

• In production software, duplicated code is generally considered harmful. In test code, duplicated code is often your friend. It is more important for a test routine to be easily understood in isolation than for it to avoid duplicating other test routines. Test code is not production code: The tests run in isolation, are generally read in isolation, and benefit from being written in isolation.

• While we’re on the subject of isolation: write one assertion per test. I like this idea, but – alas! – it is an even more radical idea in Drupal than it is in Rails or Java, because SimpleTest is (a) wicked slow at the moment and (b) linearly dependent on the number of test methods. (Or such is my impression – insert a caveat about the importance of formal benchmarking here.) I believe SimpleTest does a lot of tedious DB setup and teardown for every test method, and it doesn’t have transactional tests. One of us needs to be chained to a desk next to boombatower and forced to implement some speed boosts.

But, even if we are compelled to compromise in practice, we can still hold the ideal in our hearts: one assertion per test is great, multiple assertions per test is a compromise, and tests which interdepend on each other in a complicated way are… not good.

• Here’s one I need to think about: writing tests without names. Not that we will be doing this in PHP soon; even in Ruby it looks a little weird. But if zero names might be right, then two names is almost certainly one too many. I’ve been thinking about the Drupal SimpleTest convention of equipping every assertion with a gloriously descriptive, HTML-formatted comment:

  $this->assertTrue($bool, t('The bool should be true'));
  

  and noticing that the presence of the comment makes the test method’s name entirely redundant. Maybe I’ll experiment with using tiny, inconspicuous method names.

Converting Drupal.org’s documentation into a wiki(-like) format might help “crowdsource” the task.

Funny thing about this recommendation, which all of us have been tempted to issue at one time or another: The docs are in a “wiki-like format”. Any registered user on Drupal.org can edit a page. All of its revisions are accessible. You can show diffs between revisions.

And yet the problem is not solved. The Drupal docs are still nowhere near as good as a wiki. Or – important distinction – they are nowhere near as good as Wikipedia, which is what most people think of when they think of a wiki.

You can’t spell Wikipedia without “Pedia”

But Wikipedia is not the typical wiki. (My impression is that the average wiki on the Internet kind of sucks – the Rails wiki, for example, was legendarily disorganized and out of date until recently.)

Wikipedia’s secret is that it isn’t just a wiki. It’s an encyclopedia, an old and familiar genre with well-understood semantics. When you see a Wikipedia link to a term like ”bluegrass music”, you see more than just a link: You already know what is on the other end.

• The topic of the article is more-or-less completely defined by the title of the link.

• The entry will be written for a general audience and will not contain excessive detail or be too long.

• The entry may relate to other entries, but is designed to stand alone. No prerequisites will be assumed.

It is this implicit context that makes Wikipedia so usable. That’s why you can read a Wikipedia page filled with hundreds of internal Wikipedia links and not get lost. You know what each of those links are. And that’s why each external link gets special formatting on Wikipedia: It’s a warning. “This is not like the other links; you don’t know what’s out there. Prepare to be rickrolled.”

The encyclopedia is flat

One of Wikipedia’s other friendly features is that the Wikipedia architecture is a big flat list. True, there are “superarticles”, like disambiguation pages). And there are pages with subtopics. But there are very few special structures for creating such pages, and no real provision at all for creating trees with formally defined “parent” pages and “child” pages. So, nobody does that.

This is great because it frees people from worrying about organization. You can start a new Wikipedia article by searching for the intended title and clicking “create the article”. No need to worry about where it fits in some grand Wikipedia schema. No need to figure out how to edit the Music category to indicate that progressive bluegrass is a kind of bluegrass. No need to figure out what kind of music the Flecktones play. (Is “blu-bop” a real word? It is now!)

There is also no danger of accidentally creating two entries for the term “bluegrass music”.

A Wikipedia editor only needs to edit the content. A Drupal handbook editor must not only edit the content but also arrange it in a structure. That’s a whole new level of difficulty and intimidation.

What does this mean for Drupal?

It would actually be really nice to have a Drupal Encyclopedia – a collection of pages, designed to be read independently, which each cover a single topic in encyclopedia fashion for a general audience.

But, as a general-purpose organizational scheme for the Handbooks, the encyclopedia model doesn’t work. Sometimes the Handbooks need to contain pages with obsessively detailed instructions. Sometimes we need explanations of complex topics that go on for more than one page and need to be read in order. Often it’s impossible to capture a page’s entire context in its title, so we need to organize pages into topical sections and subsections and chapters and books.

In other words, Wikipedia’s design is not a silver bullet. We’re not trying to write an encyclopedia. We’re trying to write something different, and more complicated. No wonder it’s so much harder to get right.

• People who want to know what all the fuss is about can pick up The Lullabots’ Using Drupal, which I’m using as light bedtime reading.

• Hard-core coders who contemplate deploying Drupal should definitely read Pro Drupal Development, a truly indispensable guide to Drupal’s innards.

• Javascript is a Drupal component, too. An increasingly important one, in fact. Which gives me an excuse to plug one of my favorite software books ever: Crockford’s Javascript: The Good Parts. A blessedly short but dense book. Just the sort of thing that Tom Geller might like, I suspect.

The open-source revolution has proceeded so swiftly that some people seem to have forgotten that all documentation used to come in big paper books that cost money. Yet that technology is still surprisingly useful! And it really isn’t that much money, compared to the medical expense of continually banging your head on your desk.

I’ve spent some time off and on trying to figure out what went wrong, since a mirror with occasional errors and omissions isn’t very useful. Just today I found a very handy post on Stack Overflow that appears to have solved my problem.

I had tried using Mikkel’s command to mirror a CVS repository with git:

git-cvsimport -v -d:pserver:anonymous@cvs.drupal.org:/cvs/drupal -o upstream drupal

Which (oddly) seems to work for him – his own Drupal mirror on github works just fine. It didn’t work for me, though. Neither did this:

git cvsimport -p x -v -k -o cvshead -s _ -d :pserver:anonymous@cvs.drupal.org:/cvs/drupal -C drupal drupal

But it turns out that the -p x flag, which means “pass the -x flag through to cvsps”, isn’t correct. You have to say -p -x, like this:

git cvsimport -p -x -v -k -o cvshead -s _ -d :pserver:anonymous@cvs.drupal.org:/cvs/drupal -C drupal drupal

One tiny dash makes the difference. My new mirror appears to be correct. I’m glad someone else found this workaround, since I would probably have never found it myself.

Having said that, I’m actually going to take down my own Drupal mirror on github and recommend that everyone use Mikkel’s instead. It’s correct and, so long as he is maintaining it, it makes no sense to waste resources maintaining it twice. What I’m going to do is put up some mirrors of common Drupal modules to go along with it.

Any programming project – including Drupal projects – should use a version control system. My favorite such system is git. If you haven’t tried it I recommend that you learn all about it at the tutorial section of github, or from Peepcode’s git screencast.

Assuming that you understand the basics of git, let’s apply it to a Drupal project. The simplest strategy is to create a single git repository that holds everything in your project. You download Drupal core and modules (using FTP, the Update Status module, or drush) and you check them into git as you install them. Your custom changes get checked into the same git repository.

Here’s a couple of hints:

Use branches to separate your code from contrib

You want to make it easy to distinguish changes that you make from those made by others. Creating branches is a good way to accomplish this. When you first set up your project, create:

• A branch called core. You should check the Drupal core code into this branch.

• A branch called modules, based on core. When you install a third party module, you should do so in this branch. (Actually, it would be ideal to create a separate branch for each module, but that’s a bit of work to manage so I’ll hold off on recommending that. I’d hate to scare you away on the first day.)

• Branches for your site’s code, based on modules. You’ll probably want a development branch (I tend to name this devel) and a production branch (for which I often use master).

When you need to update core, you do so in the core branch, then merge core into modules and any other branch that depends on it. When you need to update a module, you do so by switching to the module branch, performing and committing the update, and then merging module into your development branches.

Tell git to ignore certain files

There are certain files in your Drupal installation that you should probably not have under version control at all:

• The files directory, which contains uploaded files.

• Any settings.php files.

• Utility files used by your editor or IDE: .project files, TAGS files, etc.

There are two ways to make git ignore certain files. One is to put the names of those files in a file called .gitignore in the base directory of the respository, right next to the .git directory. The other is inside the .git directory itself: If you add the name of a file to .git/info/exclude it will be excluded from the repository.

No matter which method you use, git won’t delete the ignored files – it will just pretend that they aren’t there. You can ignore whole directories, and you can use wildcards to make git ignore entire sets of files with similar names.

How do you choose which ignoring method to use? The idea is that .gitignore is part of your project: You check it in to git, and it gets copied around wherever your project goes (e.g. to your development server). So if you want to ignore a file across all servers (like the files directory, which will exist everywhere you install the code), you should put that file’s name in .gitignore. Whereas .git/info/exclude is for files that only occur in your local repository and aren’t expected to be anywhere else, like editor settings files, or the directory beneath sites which corresponds to your local machine’s test domain.

Example

Here’s a set of example commands for building a new project. We’ll assume you’ve already downloaded the necessary Drupal tar files to ~/Downloads.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

mkdir myproject
cd myproject
git init

# make .gitignore right away. 
# This will be handy later; it also
# gives us something to check in immediately. 
# You can't start creating branches without
# checking something in first

echo "files" > .gitignore
git add .gitignore
git commit -m "New Drupal project: myproject"

# create the core branch and install drupal core
git branch core
git checkout core
tar xvfz ~/Downloads/drupal-6.9.tar.gz
git add .
git commit -m "Installed Drupal 6.9 core"
git tag DRUPAL-6-9

# create the modules branch and install a 
# couple of modules.
# This time let's make the branch and check it out 
# in one command.
git checkout -b modules core
mkdir sites/all/modules
cd sites/all/modules
tar xvfz ~/Downloads/views-6.x-2.2.tar.gz
git add .
git commit -m "Installed Views 6.x-2.2"
tar xvfz ~/Downloads/cck-6.x-2.1.tar.gz
# add and commit in one command
git commit -a -m "Installed CCK 6.x-2.1"

# now get to work on your own code
git checkout -b devel modules

When it comes time to upgrade core:

1
2
3
4
5
6
7
8

git checkout core
tar xvfz ~/Downloads/drupal-6.10.tar.gz
git commit -a -m "Upgraded to Drupal 6.10"
git tag DRUPAL-6-10
git checkout modules
git merge core
git checkout devel # or any other branch
git merge modules

Now, if you need to know the difference between the current version of core and the previous one:

git diff core^ core

If you need to know the difference between the current official version of the Views module and the one in your code (perhaps because you’ve made a few patches):

git diff modules devel sites/all/modules/views

Or, for all the work you’ve done on the Views module in the devel branch since the last time you merged modules and devel:

git diff modules...devel sites/all/modules/views

Some people have accused D6 of being both easier and harder to theme, but so far all I can perceive is the “easier” part, perhaps because I’ve been elbow-deep in the Drupal 5 theming functions and know how complicated that was.

Worse, IE7 apparently does the same thing.

It’s funny how much time I spent looking for a much more obscure IE6 problem (you know, one like the other 1,001 IE6 problems) when the evidence of this one was staring me in the face. It took a while before I thought of googling “IE6 too many stylesheets bug”, because who would impose an arbitrary thirty-stylesheet limit? What would be the point of that?

I never saw it coming. Touché, Microsoft engineers!

Suppose you would like to work on the open-source Insoshi project. You have the URL of its official git repository:

git://github.com/insoshi/insoshi.git

You could simply clone this URL to your own machine:

$ git clone git://github.com/insoshi/insoshi.git

after which you could mess around with your local copy as much as you like. But it’s hard to share a local repository with your friends, or among several machines, so perhaps you’d rather create a private fork on a server somewhere. It’s easy to do this with a GitHub-hosted project like Insoshi – you get a GitHub account, then press GitHub’s “fork” button, and you rewarded with the URL for your own personal GitHub-hosted fork:

git@github.com:mechfish/insoshi.git

Now you could make a local clone of that remote fork:

$ git clone git@github.com:mechfish/insoshi.git

but there are disadvantages to that. One is that the local clone will have a different parent: its origin will be remote fork, while the remote fork’s origin is the official project repository. Ideally, you would want the two repositories to be interchangeable, so that you won’t get confused when comparing them, and so you can upload the local version to replace the remote version if it gets lost or corrupted.

You’d also like to be able to pull changes from the official repository directly into your local copy, then push them up to the remote fork, rather than having to pull every change forward through the chain: official -> remote fork -> local copy. That’s painful.

So here’s what to do:

1
2
3
4
5
6
7
8
9

git clone git://github.com/insoshi/insoshi.git
cd insoshi
git branch devel master
git checkout devel
git remote add fork git@github.com:mechfish/insoshi.git
git fetch fork
git push fork devel:refs/heads/devel
git config branch.devel.remote fork
git config branch.devel.merge refs/heads/devel

Here’s what these commands accomplish:

• Clone the official repository and cd into the local copy.

• Create a devel branch to develop on. Note that if we want to base our development branch on the “edge” version of the project instead of the stable version we should do this instead: $ git branch --track edge origin/edge; git branch devel edge

• Checkout our new devel branch.

• Add a remote named “fork” that points to our private fork on the remote server.

• Fetch the remote fork’s contents.

• Push our new devel branch to the remote fork, where it should have the same name.

• Set the config for the devel branch so that it automatically pushes changes to the devel branch on the remote fork when we do a plain git push, and automatically pulls from the devel branch on the remote fork when we do a plain git pull.

Note that with this setup you automatically get the feature that a git push will push up all changes to all branches, including the master branch. (That’s because the default refspec for remotes is refs/heads/*:refs/heads/*.) So you can pull changes from origin directly to your local copy, with the assurance that those changes will be automatically migrated to your remote fork repository when you push.

But I decided to try moving away from MAMP. One reason is that MAMP doesn’t come with certain features – for example, I’m told that it’s hard to get SSL working. Another is that the upgrade cycle for PHP and MySQL is different from that of MAMP, and I sometimes want to be able to roll my own upgrade on my own timeframe. In addition, I want to play with Ruby technologies like Merb and Rack and Thin, and I didn’t relish trying to hack them into MAMP’s config files – though it would probably be possible to do so, the Ruby docs and blogs tend to be aimed at people who are working outside of MAMP.

So I’ve just gotten everything installed. Here’s a quick sketch of the process:

• Follow Dan Benjamin’s instructions for compiling MySQL. This will involve creating /usr/local and adding it to your path, assuming you haven’t already done so.

  I’m with VanDyk, who suggests running mysql_secure_installation once you have MySQL installed.

• Follow Benjamin’s instructions for compiling your own Ruby and Rubygems. This is a more dubious move, since Apple has provided preinstalled versions of Ruby and Gems in Leopard, and they work pretty well. But I decided to install my own version so that I can keep control over the upgrades.

• I recommend avoiding the stock Apache. I spent a while trying to compile a PHP that would work with it, and ran into trouble. Instead, install MacPorts and use that to install Apache, then download and compile PHP.

Note that I installed MacPorts’ Apache, then downloaded and built the PHP source myself, using the following ./configure options:

 ./configure --prefix=/usr/local/php \
--with-apxs2=/opt/local/apache2/bin/apxs \
--with-mysql=/usr/local/mysql \
--with-curl --with-pgsql=shared \
--with-pdo-pgsql=shared,/usr/local/pgsql \
--with-pdo-mysql=shared,/usr/local/mysql \
--with-mcrypt=shared,/opt/local \
--with-openssl=shared,/opt/local \
--with-pear \
--with-gd \
--with-jpeg-dir=/opt/local \
--with-png-dir=/opt/local \
--without-iconv 

I’m not sure there’s a good reason to do this instead of just using MacPorts’ PHP. For that matter, I’m not sure that using your own MySQL is better than having MacPorts install MySQL, or using the binary distribution from MySQL AG. There are lots of options. But these options seemed to work for me.

Of course, you’ve also got to set up a php.ini and an httpd.conf and get PHP and Apache pointing at them. And I’ve still got eAccelerator and XDebug to install. It’s a bit of work. I’d advise anybody who wants to avoid trouble to stick with the MAMP option.

• Life-Line, the story of an inventor who learns how to predict the time of a person’s death to within a single hour, was the first story that Robert Heinlein ever sold, in 1939. As in all Heinlein stories, the great part of this story is the portrait of a character: The inventor, who successfully (and a bit annoyingly) remains calm and rational about the fact of death, including his own death, even as everyone around him is freaking out.

Asimov treated the story of the soothsayer as a grand historical epic (Foundation); Clarke wrote stories full of spiritual awe (e.g. The Nine Billion Names of God, 2001), but Heinlein boiled it all down to this one guy in a shabby office. He was the Raymond Chandler of science fiction – until the 1960s, at any rate.

• Kevin Kelly has a countdown clock of the days he has left to live:

My friend Stewart Brand, who is now 69, has been arranging his life in blocks of 5 years. Five years is what he says any project worth doing will take. From moment of inception to the last good-riddance, a book, a campaign, a new job, a start-up will take 5 years to play through. So, he asks himself, how many 5 years do I have left? He can count them on one hand even if he is lucky. So this clarifies his choices. If he has less than 5 big things he can do, what will they be?

I appear to have eight big things I can do – forty years, 14691 days.

• I think that a timeline which plotted the lifetimes of famous people – including the expected lifetimes of people who are alive right now – would be a great tool. I’ve loved timelines ever since I thumbed through The Timetables of History as a kid.

You need to occasionally think on a timescale that is longer than a single human life. You need to accept that people’s lives have arcs, like stories. You need to remember that the world will go on after you.

This line stuck out:

I’ve talked about the main problems imposed by the Properties pattern: performance, data integrity, and navigability/queryability. They’re all trade-offs; you’re sacrificing in these areas in order to achieve big wins in flexibility and open-ended future extensibility for users you may never meet.

Yep, that sure sounds like Drupal’s $node, $user, and $form objects to me.

First: Mark is a brave man.

Second: I hereby officially delegate my opinion on the Drupal wordmark to Mark, Dries Buytaert, Barry Jaspan, and Angie Byron. If they like it, I like it, by definition. My desire to further influence the decision is more than trumped by my belief that such artistic decisions can’t be made by a giant, public committee.

Finally: Voting. Draw up three strong contenders, then let the community respond to a questionnaire. Don’t request too much free-form feedback in open forums during your design process. You will go stark raving mad.

The firm that recently redesigned my alma mater’s logo did a great job with this: The first I heard of the project was when I received an email link to an online questionnaire. The questionnaire took ten or twenty minutes to complete, featured three variations of the logo, and asked all sorts of fuzzy questions – I can’t remember any of them, but they were something like “does this logo express the intellectual qualities you associate with the university.” Or whatever. In retrospect, it didn’t really matter what the questions were – the important thing was that they asked a sufficient number of important-sounding questions to convince me that I was participating in a thorough, serious decision-making process.

Then, a few months later, the university announced the winner, and, lo! I was happy. Because, hey, the new logo looks pretty good! And because I had been asked.

A common method of packing Javascript is Dean Edwards’ packer algorithm, which has a convenient online version. You can recognize code that’s been through the packer by looking for the cute function signature at the beginning:

eval(function(p,a,c,k,e,r){...

It turns out that you can unpack code like this using Dean Edwards’ online tool. This isn’t immediately apparent, because the tool doesn’t enable this feature by default (presumably because it’s trying to pretend that packing is an effective form of code obfuscation). But if you run the handy “reEnable” bookmarklet the packer page becomes an “unpacker” page.

Once your function is unpacked you are only halfway home, because it will look like this example (from the jQuery History/Remote plugin included with Drupal jstools):

(function($){$.ajaxHistory=new function(){var c='historyReset';var k=location.hash;var e=null;var g;this.update=function(){};var h=function(){$('.remote-output').empty()};$(document).bind(c,h);if($.browser.msie){var f,initialized=false;$(function(){f=$('<iframe style="display: none;"></iframe>').appendTo(document.body).get(0);var ...

No line breaks, not so readable. So feed it through the online beautifier for Javascript and you’ll get

(function($) {
$.ajaxHistory = new
function() {
    var c = 'historyReset';
    var k = location.hash;
    var e = null;
    var g;
    this.update = function() {};
    var h = function() {
        $('.remote-output').empty()
    };
    $(document).bind(c, h);
    if ($.browser.msie) {
        var f, initialized = false;
        $(function() {
           ...

Much better.

In the meantime, lest you suspect that I’ve made a New Year’s resolution to stop writing, I should tell you that I’ve been spending too much of my writing time posting as mechanical_fish on Hacker News, a fairly awesome site full of people who know much more about software than I.

UPDATE: From my Mollom page: “Mollom blocked 7360 spam attempts the past 10 days”. So far, so good. Mollom is hereby recommended.

UPDATE 2: That seems to have been a typo on the Mollom site: I think they meant 736 spam attempts over 10 days. Much more believeable. And still scary.

The good news about this module is that it builds upon a PHP project called, um, phpass to add better password hashing to Drupal. The traditional way to handle passwords is to ask the user for one, compute a hash function on it, and store the hashed version. Unix systems use the Unix crypt utility to make the hash. Some newer and more naive systems, like core Drupal, use MD5 hashing, presumably because it’s newer (and, therefore, niftier by definition) and also because it’s faster.

Unfortunately, it’s a bad idea to use a fast hash function to hash your passwords, because the speed makes the brute-force attacks that much more efficient. The Right Thing to do, if we trust the professionals at Matasano Chargen, is to use an adaptive hashing scheme like bcrypt, which is tricky and slow, and can be made slower and trickier as computers get faster and faster.

Unfortuately, neither my Mac nor my Ubuntu deployment box supports CRYPT_BLOWFISH, the encryption scheme that’s needed for all-out bcrypt support. So I am using the phpass fallback scheme for now. I could try to install CRYPT_BLOWFISH using the Suhosin PHP hardening extension, but would need to test this carefully to make sure I don’t break Drupal in the process.

In the meantime, I got halfway into the Suhosin downloading process before I decided to put it off until tomorrow. Part I of the process was to finally install Gnu Privacy Guard, which I have always resisted because it seemed to be a usability horrorshow with few actual uses. I only know two people who really seem to use GPG-signed mail, let alone GPG-encrypted mail. But it turns out that there’s now a handy set of instructions for installing GPG on a Mac using the MacGPG project. And I might even get GPG working with Mail once the GPGMail utility finishes being ported to Mac OS 10.5.

First we have to get git running on my Ubuntu server. I tried

sudo apt-get install git-core #do not do this!

but that led to trouble down the line. Better to just fetch the source and build from that:

sudo apt-get install libexpat1-dev zlibc curl gettext
cd ~/src
wget http://www.kernel.org/pub/software/scm/git/git-1.5.4.rc2.tar.gz
cd git-1.5.4.rc2
make prefix=/usr/local all
sudo make prefix=/usr/local install

Then, following the excellent instructions on scie.nti.st, we grab the gitosis code:

cd ~/src
git clone git://eagain.net/gitosis.git

Then:

cd gitosis
sudo apt-get install python-setuptools
python setup.py install

Next we have to create a git user to own the repositories:

sudo adduser \
    --system \
    --shell /bin/sh \
    --gecos 'git version control' \
    --group \
    --disabled-password \
    --home /home/git \
    git

We copy my public ssh key into /tmp/id_rsa.pub, then run

sudo -H -u git gitosis-init < /tmp/id_rsa.pub
sudo chmod 755 /home/git/repositories/gitosis-admin.git/hooks/post-update

And that’s the end of the server-side setup! On the local machine, we check out the files that are needed to control the server. First we have to account for the fact that I run SSH on a nonstandard port: edit ~/.ssh/config and put this inside:

Host www.example.com
    Port 32767

Then you can do:

git clone git@YOUR_SERVER_HOSTNAME:gitosis-admin.git
cd gitosis-admin

This is the directory where you administer gitosis.

Stop Designing the Neutron Bomb

It would be trivial to design a better interface than DOOM if the goal was to kill the bad guys as quickly as possible: give me a 2D map of the area with icons for enemy troops and let me drop bombs on them by clicking the icons. Presto: game over in a few seconds and the good guys win every time. That’s the design you want if you are the Pentagon, but it makes for a boring game. Jakob Nielsen

Facebook and Google – and, one fears, a bunch of current and future startups – operate on the assumption that sharing links with your friends is a tedious chore. Telling your friends about your most recent purchases is a chore. Figuring out which addresses in your book correspond to your best friends is a chore. So they try to automate these chores away: In the spirit of Jakob Nielsen’s high-efficiency first-person shooter, they build one big flat list of all your friends and offer you an elegant one-button interface: SOCIALIZE.

Hello? People use social networks because they are fun. Tweaking your Friend list is fun. Personally choosing the links to be sent to your friends is fun. Choosing when and how to poke people is fun. Flirting is fun! Deciding which of your friends should be introduced to each other is a source of social anxiety, but it is also fun.

Feel free to automate the cleaning of my laundry and the removal of my trash. I don’t really enjoy those things. But stop thinking of my social life and my public persona as tasks that I want to outsource, instead of as hobbies that define my personality.

Fun is Deadly Serious

Perhaps I should stop writing right now. Once you’ve told people to stop designing out the fun, is there any more to say?

Maybe. The problem with fun is that many people don’t respect it. They think it’s frivolous, and trivial, and arbitrary. Because people share links “just for fun”, designers feel free to quietly, unilaterally change the way that shared links work. “Why are you taking Google Reader so seriously?”, they say. “Lighten up and share your data!”

These designers are insane. Fun is serious business. Just look at how animals have fun: Cats think that stalking fast-moving objects is fun, dogs think that herding and chasing are fun, gerbils think that burrowing and chewing are fun, and parrots think that – believe it or not – social networking is fun. For animals, fun is associated with the practice of vital survival skills.

Humans work the same way. Reproduction? Fun. Looking at babies, especially your own? Fun. Hunting, watching birds, playing Half-Life? It’s fun, and it’s also a way to practice the stalking skills that you’d use for hunting game or fighting wars. Chess? Strategic training for warfare. (Just ask any well-educated kid from the Middle Ages.) Gardening? Practice for farming. Stamp collecting and Pokemon? You’re practicing taxonomy, exercising the parts of your brain that evolved to remember which things you can eat, which things can eat you, which are poisonous, which are likely to be found under trees in July.

Social networking is one of the most fun things of all, because it’s a survival skill that humans are heavily invested in. We’re designed for it. Human language itself is a social networking tool.

Some fun activities are no longer vital for survival: We’ve invested lots of time, energy, and money to ensure that I can eat without knowing how to tell one plant from another, defend myself without knowing how to shoot, and stay warm without flint and tinder. Social networking is not in this category. Social networking may be more important now than ever before in human history. Many historical humans had very little interaction with strangers. They didn’t marry anyone that their parents didn’t already know, and their friends lived within a ten-minute walk. (Of course, even these people had a social network that was too complicated for a computer to manage.)

Modern social networks are very complicated. We travel a lot. We move through many different social groups during our lives. We have multiple overlapping circles of friends. We have technical friends, gaming friends, friends from work, friends from school, friendly customers, friendly teachers, friends we aspire to marry, friends with benefits, platonic friends. We have friends who we met once at a conference in 2006, friends who we went to college with but don’t see more than once every three years, and friends who we used to see every day but who just moved to Idaho. We have relatives, who may or may not be our friends. We have the relatives of friends, and the friends of relatives. We have fundamentalist Christian friends and polyamorous anarchist friends.

Incidentally, we also have enemies.

Mismanaging your social interactions can have terrible consequences. It can cost you your reputation, your spouse, your children, your inheritance, your job, your career, your freedom, and your sanity. If you make the wrong friend, and that friend turns into a stalker, it can cost you your life.

So:

• Personally micromanaging your social network is fun.

• The reason it’s fun is that humans are designed for it. This, in turn, is because it’s a vitally important personal skill that determines your income and your happiness. This is especially true in the 21st century.

• Nobody is going to entrust their social network to a computer, not ever. Computers have not spent millions of years evolving their social skills. Computers are stupid. You have not solved the strong AI problem. If, by chance, you do invent a computer that is smarter than a human, nobody will trust that, either.

• Build tools that empower people to make better decisions, not tools that try to make decisions for them.

But I went with Ruby anyway, at least for version 0.1 – partly to keep myself in practice, and partly as an excuse to work out with RSpec, the Behavior Driven Development (BDD) framework for Ruby.

With BDD, before you write your code, you write a spec. Here’s a section of one of my specs – it describes an Environment object that can parse a Unix command line and pick out the arguments and the option flags:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

describe Environment, "created from the command line" do
  before(:each) do
    @env = Environment.new
  end

  it "should set the usage message attribute" do
    args = %w(foo bar baz quux)
    @env.parse_command_line(args)
    @env.usage_message.should_not be_empty
  end

  it "should recognize arguments that are not options" do
    args = %w(foo bar baz quux)
    @env.parse_command_line(args)
    @env.should have(4).args
  end

  it "should throw an exception if an illegal option is provided" do
    args = %w(foo -z bar)
    lambda { @env.parse_command_line(args) }.should raise_error
  end

  it "should allow the cvs path to be set" do
    test_path = '/bin/cvs'
    args = ['--cvspath', test_path]
    @env.parse_command_line(args)
    @env.get_option(:cvs_command_path).should == test_path
  end

  it "should be invalid if cvs path does not exist" do
    args = ['--cvspath', 'nonexistent']
    @env.parse_command_line(args)
    @env.should_not be_valid
    @env.errors.should have_at_least(1).error
    @env.errors_on(:cvs_path).should have(1).error
    @env.errors_on(:cvs_path).should match(/not exist/)
  end
end

The idea is that you write a sentence about what the code should do, along with an executable description that demonstrates the sentence. Then you write the code itself until the description runs without failing.

Advocates of Test-Driven Development (TDD) will recognize this as nearly the same thing. But it does have a few advantages:

• BDD avoids using the word “test”, which carries uncomfortable connotations like “broken” and “buggy” and “ISO 9002” and “let’s do that last, after the documentation”. BDD uses words like “describe” and “should” to guide you into a proper, positive frame of mind.

• BDD in Ruby uses nifty readable syntax. The syntax is astoundingly addictive. Why read this:

1

assert(wallet.dollars >= 2e6)

when you can read this:

1

wallet.should have_at_least(2e6).dollars

or this:

1
2

bank = mock('a bank with 2 million dollars')
bank.should_receive(:withdraw).at_least(:twice).with(1e6).and_return(:ok)

Oh, sweet RSpec mock syntax. How I wish you had an equivalent in other important languages, like PHP!

Well, the good news is that PHP has testing advocates of its own. Mock objects are apparently well covered by Simpletest, which just happens to be Drupal’s preferred PHP testing library. And the syntax looks familiar – it’s quite nice, despite some additional clutter:

1
2
3

<?php
$observer = $this->getStub('Observer', array('update'));
$observer->shouldReceive('update')->once()->with('something');

Meanwhile, at least one person, Pádraic Brady, is working on a BDD framework for PHP: the PHPSpec project. Unfortunately, the results are… less nice:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<?php
class DescribeNewBowlingGame extends PHPSpec_Context {
  private $_bowling = null;

  public function before() {
    $this->_bowling = new Bowling;
  }

  public function itShouldScore0ForGutterGame() {
    for ($i=1; $i<=20; $i++) {
      $this->_bowling->hit(0);
    }
    $this->spec($this->_bowling->score)->should->equal(0);
  }
}

Compare this to the RSpec code which inspired it:

1
2
3
4
5
6
7
8
9
10

describe Bowling do
  before(:each) do
    @bowling = Bowling.new
  end

  it "should score 0 for gutter game" do
    20.times { @bowling.hit(0) }
    @bowling.score.should == 0
  end
end

It’s enough to make you cry.

The thing is, I’m completely convinced that Pádraic is doing the best he can. I am no expert on PHP syntax, having learned it by osmosis from Drupal code, and maybe after I finish Programming PHP I’ll know better, but PHPSpec seems to be fundamentally stymied by the ugly syntax of PHP. Specifically:

What’s :this?

Why, it’s PHP’s inability to understand object scoping! You would think that declaring _bowling to be private to a class would be enough of a clue, but it looks like you’re still obligated to refer to it as $this->_bowling.

Little things matter

Ruby uses object.method syntax. PHP uses $object->method. They look so comparable! That is, until you run into a chain like:

$this->spec(foo)->should->equal

which is less readable than:

this.spec(foo).should.equal

It’s all about the typography: the whitespace above the tiny dot separates the words better and makes their shape easier to recognize.

It’s good to be an Object

In Ruby, everything is an object, every object is a child of Object, and Objects can be monkey-patched. So you can magically attach new methods like should and should_not to the Object class and then write things like:

@bowling.score.should be_big

Here we’re calling the should method on @bowling.score, which is probably an Integer, although it might be a BowlingScore object, or a Real, or even Imaginary if we’re bowling on the planet Vulcan. Ruby does not care. Ruby can roll with those punches. Ruby rocks.

Alas, PHP prosaically insists that you call the should method on specific objects that can actually understand it. So we have to wrap the subject of should in a $this->spec(), like this:

$this->spec($this->_bowling->score)->should->equal(0);

This line makes my brain hurt because it’s got two instances of $this, both of which are 100% free of significant meaning. The thing which they refer to – the enclosing PHPSpec_Context object – is an irrelevant piece of scaffolding that I do not want to have to think about.

The PHP version of the Bowling spec reads like this:

This paragraph is a spec, and it-describes-Bowling. Consider the game of bowling that we will discuss in this paragraph. The score-should-be-zero-for-a-gutter-game. That is, if a ‘hit’ that scores zero pins happens twenty times, this sentence of this paragraph will be true: this paragraph’s game’s score should equal zero.

Here’s the RSpec version:

Let’s talk about Bowling. Consider a game of bowling. The score should be zero for a gutter game. That is, if a ‘hit’ that scores zero pins happens twenty times, the game’s score should equal zero.

(Note: Fun as it would be to write down the prose equivalent of a for loop – it would look like a number-theory textbook – I decided not to blame PHP for that. I’m pretty sure the language does have iterators…)

PHP’s syntactic cyanide is so bitter that I wonder: is PHPSpec worth it? If the language itself insists on mangling my syntax, why should I bother trying to apply the subtle shading that is BDD? It just gets lost in the noise. Here’s a comparison from the PHPSpec docs themselves: the TDD version (PHPUnit):

$logger = new Logger;
$this->assertTrue($logger->hasFile());

and the BDD version (PHPSpec):

$logger = new Logger;
$this->spec($logger)->should->haveFile();

Frankly, I think the first version is clearer: it’s shorter, the call to hasFile() is in its natural location, and since neither version is readable, why not pick the one that’s closest to idiomatic PHP? Others seem to agree with me; just look at this comment thread.

Pádraic has his work cut out for him, battling heroically against the fundamental structures of the PHP universe. I really feel for the guy, and would sincerely like to help. My personal inclination is to build a macro processor that allows you to write something sensible and have it JIT-compiled into PHP. But maybe I can get used to PHPSpec if I make some subtle vocabulary changes:

$this->thing($this->_bowling->score)->thing->should->equal(0)

This thing, this PHP syntax thing… we will learn to cope with it.

Update: Jan 6, 2012

Dan Bernardic writes:

“All PHPspec is missing is a DSL on top of what he has. Except that I expect it would be a better idea to implement a way for ruby to run PHP code and inspect PHP memory state, just cause rspec for ruby already exists…”

and includes a proof-of-concept Gist.

I’ve toyed with this idea myself - which is to say, I’ve sat in an armchair and imagined it, not actually hacked on it - but there are drawbacks. The biggest is that it’s not enough to test one’s PHP code in isolation; one should test it in an environment that’s as close as possible to the production environment. Unless you plan to run your production PHP code inside a Ruby wrapper - and, believe me, you don’t - a Ruby-with-embedded-PHP testing framework is going to trade reliability for syntax, and that’s not a good trade unless the syntax is truly brainf**ked.

I tried the tricky answer before I gave up and adopted the simple answer:

$ sudo ln -s /usr/bin/spec /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/bin/spec