Midnight Oil

Tonight I tried to migrate from Rails 1.2.1 to 1.2.3 using the vendor branch methodology I described earlier. Well, after about an hour of playing around and finally running the svn_load_dirs.pl script that they recommend, I had a tagged copy of Rails 1.2.3 Or at least, that’s what the process promised.

Well, I’m sort of the conservative type, especially with configuration management. I ran a diff on the 1.2.3 release from the Ruby on Rails repository versus the 1.2.3 release in my repository. As soon as I saw it start cranking out differences, my heart sank. Maybe I ran diff wrong, maybe I didn’t clean up all the working material from svn, and maybe a thousand other things. Still, the fact that what I had in my repository was not bit-for-bit identical to the official 1.2.3 release sealed the deal for me. Rather than going forward with an unknown, possibly mangled copy of Rails, I just gave up on the vendor branch. I swallowed my pride and just downloaded the official release and put that in the vendor directory of my project, skipping all the tagging and whatnot. The alternative of never knowing whether future bugs were in my code or due to my mangled version of Rails was simply too scary for me.

I still stand by my assertion that vendor branches are great for plugins. In most cases, the plugin code will be small enough that managing the vendor branch updating will be simple. For something as large and complex as the Rails core, however, it is simply too risky of a proposition.

Ryan and I have been going back and forth about starting a business for a while, and it seems that we are equally in the dark about the whole thing. Luckily, up to this point, we have not been doing much of anything that one might call business-like. That’s not to say that we do not behave professionally as software engineers, just that so far we have not really thought in terms of money.

Recent events, though, have forced the issue into the front. Ryan has been becoming more and more popular as a regular at various web guru meetups in San Diego. He has promised for a couple weeks now to put up some postings about some of what he has learned. From what he tells me, our work on Obsidian Portal has drawn some attention. Besides the content of the site, people have questions about how we designed our software, how Ryan is handling the layouts, and various other technical aspects of the site. Assuming people like what the answers we give, I want them to be able to remember us and make contact in the future, if they have further questions or ideas for us.

So, the basic need right now is to get some business cards printed that we can hand out at various events. Seems simple enough, right? Well, sure, but what to actually put on them? We needed a name!

For several years, Ryan has been sitting on a domain name that he has used for his personal e-mail address and some other small projects. I never thought much about it, but just the other day, he suggested it for our company. In truth, I was quite flattered that he would do this. As a namer of all things (goldfish, house plants, bicycles, you-name-it), I know the value of a good name. If you use your best name on a goldfish, and it dies the next day, then not only have you lost your pet, but you have also lost a great name. So, for Ryan to offer the name like he did, it shows he actually has some confidence in what we are doing. Plus, it is just a really great name.

So, without any fuss or agonizing or complicated domain-name mangling, we made the decision to name ourselves…AisleTen! It has a great sound, is easy to remember, and even has a pseudo-definition.

To sweeten the pot, Ryan has been working on a logo and a business card design. Take a look for yourself:

All we need to do is find an inexpensive print shop and crank a handful of these out. From there, we can start to build an identity as a couple of sharp guys trying to make the web a better place.

Maybe this is spelled out somewhere else, but I struggled to find a way to create my own validation methods for my models. While the standard, built-in validation methods cover a lot of ground, there are always things that have to be done by hand. To the rescue comes validates_each.

In my case, I needed to validate that a certain field was either nil or matched a regular expression. Normally, you would use validates_format_of, but it did not seem to support allow_nil as an option.

To get this custom validation, I used the following:

Overriding validates_each in your model class makes it possible to create any sort of crazy validation that could be necessary. It might not be as pretty or small as the validates_such_and_such, but it’s nice to know the power is there.

Ok, imagine that you have just created the most awesome website in the world for the greatest game ever, Dungeons and Dragons. Now, also imagine that no one knows about it. That’s about where I am right now.

Obsidian Portal has reached a stage where we are ready to begin beta testing. There is just enough functionality to make the site useful, and all that’s lacking is content. So now, I’m splitting my time between implementing features, adding content, and trying to think of ways to promote the site.

On my wife’s advice, I started looking around for college gaming groups. Lots of D&D groups form around colleges, and often larger organizations also form in order to help students find local games.

I finally managed to contact Mike Roselli of North Carolina State University. He is the president of the Collegiate Association of Table Top Gamers (CATTG), a multi-university organization dedicated to promoting table top gaming (including D&D and RPGs). Mike has expressed a lot of interest in Obsidian Portal, but he has some reservations about the fact that we are a for-profit enterprise. Perhaps I should tell him that we have a long way to go before we see anything that could be considered “profit”

The CATTG presents a wonderful opportunity for OP. If we can get exposure to college gaming groups and develop a core following, it would be excellent. For a shoestring-budget site like ours, the only kind of marketing we can afford is the word-of-mouth viral marketing. Luckily, that’s exactly the kind we want. Hopefully, we are on our way.

RoR plugins are a great way to get small chunks of useful functionality. I currently use some great ones like acts_as_authenticated, authorization, acts_as_taggable, and friendly_identifier. By the time anyone actually finds this post, I’ll probably have included half a dozen more.

Unlike the compiled world where you grab a library and never see the source, with Rails plugins you have access to the source from the start. This is a great thing, as very often, the plugins are buggy or incomplete. They do 95% of what you want, but not everything. Or, you have a weird setup the author never imagined and his/her test cases do not accurately represent your application. With a compiled library, like a JAR, you are screwed at this point.

In RoR, you can just go to the plugin directory and start hacking away until things work the way you want. Most of the plugins I have are very simple, comprising less than 50-100 lines of code total. Instead of providing complicated functionality, they provide a clean, simple way of solving a single problem. So, once I understand how it’s done, I can modify them to support my particular needs.

Unfortunately, once you start editing the code, you have effectively forked a new distribution. For most people, this involves checking the modified code into your SVN repository and going on your merry way. The problem arises when updates are published to the plugin. What do you do? Manually copy the changes from the new version into your code? Delete your version and re-run script/plugin install? Just ignore the updates? If only there were a way to automatically include the updates from the new version, while at the same time preserving the changes that you added yourself!

Luckily, there is a way to do this, called vendor branches. The entire methodology is detailed in the online SVN book in the vendor branches chapter. The goal is to include third-party code in your project, allow you to make modifications, yet make it easy to include a new version when released. If you want the whole story, read the book, since I will just give quick instructions for RoR people.

1. Prepare your repository

Create a top-level directory (next to trunk, tags, and branches) called vendor. Then, create a subdirectory for your plugin in the vendor directory. Finally, create a current subdirectory in that plugin. Afterwards, your repository structure should look something like:

/myrepo
  / trunk
  / tags
  / branches
  / vendor
    / some_plugin
      / current

2. Get the source

Download the source for the plugin you want into the vendor/some_plugin/current directory. This can be done by inflating a .tar or unzipping a .zip or whatever. I prefer to export the latest SVN revision of whatever plugin I’m downloading (assuming it’s in someone’s svn repo) and then copying the files into the vendor/some_plugin/current directory. Note: If you do this, make sure you export and not check out. Exporting strips out all the .svn folders which you definitely do not want at this stage. I don’t know how to do an export using command-line svn, since I use a client called SmartSVN.

3. Commit the current

Add and commit all the source files into your repository. At this point, you have all the plugin code in your repository inside the current directory.

As a tip, I like to add the original repo and the revision to this commit message. It usually looks something like this:

Vendor drop of some_plugin.
repo: http://someguys/svn/repo/some_plugin
rev: 1234

4. Tag the revision

Create a tag in the vendor/some_plugin directory. This is accomplished via an SVN URL-URL copy (the default copy). So, you copy the vendor/some_plugin/current to /vendor/some_plugin/1.0 (or whatever version you downloaded). If there are no tagged releases of the plugin, I name the tag after the revision that I got. For example, /vendor/some_plugin/rev_1234

Directory structure:

/myrepo
  / trunk
  / tags
  / branches
  / vendor
    / some_plugin
      / current
      / 1.0

5. Copy the tag to your trunk

Copy the tagged source to your trunk, into the vendor/plugins directory of your RoR app, using the plugin’s real name as the final directory. Again, this is accomplished by an SVN URL-URL copy.

Directory structure:

/myrepo
  / trunk
    / my_rails_app
      / vendor
        / some_plugin
  / tags
  / branches
  / vendor
    / some_plugin
      / current
      / 1.0

At this point, the copy in the trunk is based on the 1.0 tag in the vendor branch.

6. Edit to your heart’s content

You’re done! Now you can work on your trunk, including the new plugin. If you need to modify it in any way, just do it. Make your changes and commit. Do this as much as you need. Essentially, you can treat the plugin like it’s your own code. One caveat: Do NOT make any changes to the code in the top-level vendor directory. This is only for holding pristine releases from the third-party.

7. When a new version is released

The whole point of all this mumbo-jumbo was to support including features of a new release. When that happens, repeat steps 2-4 with the new version, overwriting /vendor/some_plugin/current with the new release. After that, current in the vendor branch will point to the new release, and there will be a new tagged branch (ie. /vendor/some_plugin/2.0)

At this point, you have 1.0 and 2.0 in your repository, and SVN knows the differences. So, you can do a merge from 1.0 to 2.0 and apply the results to your trunk, in the vendor/plugins/some_plugin directory. SVN will do a diff between 1.0 and 2.0, figure out what changed, and apply those changes to your trunk. As long as your edits do not conflict with the changes, it is seamless. Re-run all your tests to make sure the new version hasn’t broken anything, then commit. At that point, you have upgraded to 2.0, but retained all the modifications you made. Plus, it’s very easy to revert back to 1.0, as it is a simple rollback.

Update (2007-05-18): We just executed a vendor branch upgrade. Take a look at the detailed instructions on how to go about upgrading a vendor branch.

Spending an extra ten minutes going through the motions of a vendor branch can be frustrating when all you want to do is get your plugin running now! Still, investing that ten minutes can save you hours of pain when trying to integrate a new version in the future. Plus, there is just a certain sastisfaction to be had in knowing that you are doing things the right way.

I went ahead and disabled the .htaccess password on Obsidian Portal. I guess I was way too optimistic that users would be trampling down my door. Instead, I think I just made an unnecessary obstacle to them getting in. Probably not a great idea.

It is free and clear now, so hopefully people will be more comfortable with using it.

Lesson learned

Unless you have a very good reason to restrict access, it is probably a bad idea.