Why you should always allow version 1 to be specified

December 11, 2008

This is one of those things that is easier to discuss in specific, so I want to say that I'm not picking on ZFS here. Well, not too much.

Like a number of other filesystems, ZFS has several different versions, with later ones adding new features not supported by earlier code; this change is marked with an on-disk version number. Sensibly, ZFS allows you to explicitly set the version of a new filesystem when you create it, so that you can use a new system but create a filesystem that an old system can read (necessary in, say, SAN environments, where a filesystem may have to be brought up on a machine still running an older OS release).

(Similar versioning is common in many contexts where you have persistent objects and multiple generations of them floating around.)

However, ZFS made an interface mistake. On systems that only have ZFS version 1, you cannot explicitly set the version to version 1 when you create a filesystem; you can't explicitly set the version at all, presumably because there is only one version to start with.

This is a problem because of how it affects tools that sit above ZFS. In order to always create version 1 filesystems, they have to detect whether they are running on an original ZFS system (that doesn't allow the version to be specified but where an unversioned create gives you a version 1 filesystem) or on a newer one (where versioned create is allowed but an unversioned create gives you a more recent filesystem, so they have to use versioned create).

And thus: if you are going to version things and to allow older versions of things to be created (and you should), you should build in the ability to ask for a specific version right from the start, even when you only have version 1. 'Create with version X' should be one of your initial APIs. Do not wait until you have version 2 to add it, because it will not help people as much as you think.

(Remember: anyone who is specifically creating older versions of objects quite likely has systems running the older version of your code (otherwise they don't have much use for those old versions). Which means that their code probably has to run on top of that older version of your code.)

The other way to put it is that if you start out with an unversioned 'create' operation and no versioned 'create', its API is not really 'create with current version' but 'create with version 1', because this is its actual behavior. You should not then later change its API behavior to be 'create with current version'; if you do, you are causing problems precisely because you have changed the API.

Written on 11 December 2008.
« What sort of user interfaces the web is good for
Why syndication feed readers (and web browsers) should fail gracefully »

Page tools: View Source, Add Comment.
Login: Password:
Atom Syndication: Recent Comments.

Last modified: Thu Dec 11 01:49:03 2008
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.