Illumos's problem with its VCS commit messages
Quite a number of years ago I wrote an entry on the problem with the OpenSolaris source repository, where I called out Sun for terrible commit practices. At the time I thought that the public OS source repository had to be just a series of code snapshots turned into an external repository, but someone from Sun showed up in the comments to assure me that no, the terrible commit practices really were how they worked. I am glad to say that Illumos has fixed this problem in the Illumos master repository.
Well, mostly. Illumos does not routinely bundle multiple unrelated changes together into one commit the way that Sun used to, and (unlike Sun) their bug reports and so on are clearly visible. But they still have one problem with their commits. To show you what it is, here is a typical commit message:
6434 sa_find_sizes() may compute wrong SA header size Reviewed-by: Ned Bass <...> Reviewed-by: Brian Behlendorf <...> [...] Approved by: Robert Mustacchi <...>
That is the entire commit message. To know anything more, you must know how to look up the Illumos issue associated with this. Unless you do this, or are sufficiently knowledgeable about Illumos internals, it is probably not obvious that this is a ZFS bug; if you were scanning the commit logs to look for potentially important things for a ZFS fileserver environment, for example, this commit might not jump out at you as something you'd like.
Minimal commit messages like this are not what you'd call best practices. Pretty much everyone else has settled on a style where you at least describe a bit about the issue and the changes you're making. This lets people follow along just from the commit logs alone and provides a point in time snapshot of things; external bug reports may get updated or edited later, for example.
Beyond just the ability of people to follow the commit logs, this means that the Illumos commit history is not complete by itself. Since all the real content is in the Illumos issue tracker, the commit logs are crucially dependent on it. Lose the issue tracker (or just lose access to it) and you will be left to reconstruct scraps of understanding.
And, as far as I know, the Illumos issue tracker is not a distributed, replicated resource. There is one of it, and you cannot clone its data the way you can clone the Illumos repo itself.
(I'm sure it's backed up and there's multiple people involved. But there's still centralization here, and we've had things happen to centralized open source resources before. If nothing else, life on the Internet has taught me that almost everything shuts down sooner or later.)
At one point I thought it would be nice to at least include the URL of the Illumos issue in the commit message. I'm not sure of that any more, although I'm sure it'd help some people. It feels like a half-hearted bandaid, though. On the other hand, ZFS on Linux does put in URL references when porting Illumos changes into ZoL (eg) and I do like it, although it's a somewhat different situation.
(I don't expect this part of Illumos development culture to change. I'm sure the people doing Illumos development have heard all of these arguments before, and since they're doing what they're doing they're clearly happy with doing it their way.)