On Feeds and Backwards Compatibility

Zach Hale notes:

Should I choose RSS or Atom?

Who cares? I don’t. I bet if I asked everyone I had contact info for, only a few would prefer one or the other (though hopefully one in particular).

I've got a preference — Atom. This is mostly because of the fact that's it's one de jure standard, as opposed to the at least five de facto RSS standards.

More to the point, I agree with the underlying argument:

And that being so, it makes no sense to put both standards (if not different versions of each) in the auto-discovery tags, especially for big sites like Flickr and consumer blogging software like WordPress. [...] For the rest of us, our feed readers could care less. So please stop confusing us.

Sadly, I also know the history behind this. Back in the "bad old days", feed readers did not follow the robustness principle. So, websites had to deploy a sort of "inverse robustness principle", to make sure that as many feed consumers as possible could read the content. The good news is that today, any decent feed reader can read most feed formats. The bad news is that no one (or not enough people) have bugged the feed producers (e.g., Flickr) into fixing it. The solution? File a bug and remind them of Postel's law. Of course, only file said bug if no one else has already done so — we don't need to annoy the developers.

On Version Control "best practices"

Source code management, or version/revision control, is one of the most useful tools that a developer has, especially if this person works with others on a shared code base. However, I've recently realized that some people don't understand what a good "commit"^[1] entails. (I'm not naming them, or whether they come from my professional or hobby "spheres of influence".) It doesn't matter whether you're using Subversion, Bazaar, or even CVS. There are a few principles that you should consider when you make a "public" commit (as opposed to a "local" commit, which is supported by distributed version control systems):

• Limit your commit to one discrete idea. This can be fixing a bug or adding a new feature. Obviously, there is an exception when you happen to fix a bug by creating a new feature, but these instances tend to be rare. The big reason for this principle is that developers are (generally speaking) not infallible. If it turns out that the commit introduced bugs and/or regressions, it is easier to revert an entire revision (through whatever means your SCM provides), than to comb through the differences between the revisions in question for the "tainted" code.
• Good commit messages are key. Due to the way that most source code repository viewers work, it is considered good practice to summarize the commit in the first line, and then give a more detailed explanation in subsequent lines. This is actually similar to how writing is taught (at least in the US): provide a topic sentence in which you summarize what you're going to write about, and then write your content. In this case, though, you don't need a summary/closing statement at the end.
• If your project management and/or your SCM software supports it, annotate your commit as much as possible. I'll give two examples as to what I mean:
  1. Bazaar lets you annotate your commit with a couple of metadata flags when you invoke bzr commit: --fixes=[BUG] and --author=[AUTHOR]. The flag --fixes lets you annotate which bug this revision is supposed to fix, and --author lets you specify the author of the code, e.g., if you are just committing a patch for someone else who doesn't have the proper permissions to do it themselves.
  2. There is a post-commit hook for Subversion, distributed with the Trac project management system, that allows tickets to be changed based on the existence of certain key phrases in a commit message. For example, the message Add foo. Addresses #12345 adds a comment to ticket 12345 with that commit message and a link to the revision, whereas the message Add bar (fixes #12345). performs the same task as the "addresses" phrase, plus it sets the ticket status to "closed". In my opinion, putting the "fixes" or "addresses" phrases at the end of the first line is preferable to putting them in the detailed explanation.

Hopefully, this is helpful to those who are new to using version control systems, and those people who are the "gatekeepers" of the repositories. Comments and criticisms are welcome.

¹: The difference between a "commit" and a "revision", in my view, is that a revision is a patch that has been committed to a repository, whereas a commit is the process.