Yesterday, I received a 1,063 word email from a non-profit organisataion asking me for advice on whether or not they should use Rails or Django for their new project. They begin with:

We found your answers and profile on Stack Overflow. We’re reaching out to you because we’d like your advice on a new nonprofit project, name, and the language/app framework we should use to develop it.

We have a fairly small budget to build the framework and to do betas of the first seven sites, so it’s crucial we pick the right framework. We are trying to choose between Django and Rails, and we want to make the right choice.

Quite obviously, my answer is going to be heavily biased in one direction. I’m sure you can guess which one.

Before yesterday, I’d never even heard of this charity, nor spoken to the person who sent me the email. Basically, up until this point, we’ve done nothing for each other. Their questions obtusely relate to Rails, and definitely doesn’t relate to what I get paid to work on.

So I read the email anyway. It explains what the charity does and what they’d like their new platform to do. Then at the bottom, they ask if I could “take a look at the high-level requirements” and link me to a Google Docs Spreadsheet. Inside this spreadsheet, there’s 32 very wordy questions, like this one:

We need the front ends and backends to run fast. Many of the backend pages will have fairly intensive reports drawing on lots of data from user pages, such as nonprofits being able to run reports of total donations over periods of time, recent donations, etc. We think speed is a top priority.

Each question, by my estimates, would take one hundred to five hundred words to answer adequately. So at a minimum, around 3,200 words of mine to answer their questions. This is from a complete stranger in a private conversation between myself and them. Do you know what other situation this happens in usually?

Oh yeah, paid consulting. But there’s nothing in the email that indicates that I will get anything more than a warm and fuzzy feeling from answering it.

Like I said before, this is not related to anything that I do. This is extra work. It’s in a private conversation, so my answers won’t benefit anybody else. If this question pops up again, chances are that I will have to answer it again, and that’s not cool.

These kinds of emails are basically a three-times-a-week deal, and I’m over it. While I enjoy helping people for free, I will only do so in a public forum where other people can benefit from the answers. If you want to contact me privately, then I will ask for some sort of reward for it, because very few people are going to benefit from it.

These kinds of questions have no regard for my time, and all I get from them is a feeling of being used for my talents. Kind of like a whore, just without the money changing hands thing.

No more.

One year, four months ago I moved out of a place in Camperdown in Sydney to a more remote suburb called Narwee. If you don’t know where that is (and judging by the conversations I’ve had with many of you, nobody does), it’s a South-Western suburb of Sydney, best described as “Go south to the airport, then about as far west”. You could Google Maps it if you like. I’ll wait.

It was there that I moved in with a guy called Tim and basically rented a room and shared the house for $200. It suited me fine, as I spent quite a lot of that time in there writing a book. The trainline nearby got me into and out of the city every single day that I needed it, bar one or two times where somebody decided to fight one of the trains.

When I came back from Adelaide recently, Tim arrived back also and told me that he has a friend who he would like to move in and so he asked me (very nicely, might I add) to move out by the end of January. Fair enough, it’s his place. This was on the 28th of December.

So then I needed to find a place. If I stay until February this year, then it’ll be two years in Sydney. During that time, I’ve always heard Melbourne compared to Sydney favourably. Things like “Melbourne’s like Sydney, but with more fun”. It also helped a bit that my friend Tom (who I caught up with over Christmas) was suggesting that I should move to Melbourne as well so that we could hang out.

I was cooking dinner on the 29th and felt like I was doing nothing to further the situation. I needed to move out, but my weekend plans weren’t exactly conducive to that. So I thought “fuck it” and sent out a tweet asking if anyone had a place for me to (temporarily) stay in Melbourne.

Tom replied with a half-joking, half-indignant tweet that I should have messaged him first and asked if I could stay there. I sent him a message and he replied and said I could stay at his. The very next day I drove the ~900km down to Melbourne to stay at Tom’s house.

At that point, I had no fucking clue what I was doing in Melbourne. It was one of those spur-of-the-moment things. The drive flew by, thanks in part to the Hume Highway dual-carriageway upgrades and the most-excellent Back to Work podcast.

Then, I got to see Melbourne for the first non-going-through-in-a-bus-to-the-airport-for-railscamp time. This city reminds me so much of San Francisco, from the cafés, to the over-population of hipsters (which is a con, not a pro) to the amazing food and friendly people. Ross Hill actually wrote about these things, and I can totally agree with him. I’m actually writing this from Inspire9 right now!

I got to experience NYE in Melbourne with some great friends and all of those things combined are what sold me on Melbourne. So I’m moving there (which is “here” right now, but let’s not get technical).

I still had no fucking clue where I wanted to move, but at that point it had to be Melbourne. Some point after that, Tom and I are talking and he brings up that the guy who sold him his apartment (that he shares with two others) had another that he was looking to rent out also.

I got in touch with him, and he showed me the place. It is the best place I've ever had the pleasure of looking at. Wooden floorboards, a nice upstairs area, two bathrooms, four bedrooms (one will be used as a study / storage area), gas stove kitchen, nice patio, and so on.

On Friday, I looked it over again with two other prospective housemates and they both agreed that it was nice. One of them backed out due to how long it is out of town, and the other one doesn’t mind. So I told the agent that I would absolutely love to lease the property.

This morning, I went into the agent’s office, handed over the first month’s rent and signed the lease agreement.

I’ll be moving down and in on the 21st of January. See you around!

You may remember him from that little hosting company called Site5 he started when he was 15. You know the one that was one of the, if not the first, hosting company to offer Ruby on Rails support.

I had the pleasure of working with Matt around September last year and ended up visiting him in San Francisco. We went to Antonio's Nut House where we drank and played darts (and ate way too many free peanuts). Then we went back to his apartment where I got to sleep on an air mattress. That morning we went for bagels at a place not too far away from the Nut House. Those are my favourite memories of San Francisco.

He was such an amazing guy and will be terribly missed.

Testing Validations

RSpec supports the shoulda-matchers gem and I see a lot of people using this to test validations on their models, and this is the first test that they’re writing. I personally think that this is the wrong way of doing things.

The first test should be one that follows the exact steps that the user would need to do in order to approve this functionality.

In the example test (written in Capybara’s syntax) below, the user fills in the form (ignoring one of the required fields) and then should see that there’s an error on the page.

visit root_path
click_link "Posts"
click_link "New Post"

fill_in "Title", :with => "Deciding what tests to write"
click_button "Create Post"

within("#flash_alert") do
  page.should have_content("Post could not be created.")
end

within("#post_form .errors") do
  page.should have_content("Body cannot be blank")
end

Or if you prefer Cucumber:

Given a user is creating a new post
And the user leaves the post text blank
When the user clicks "Create Post"
Then they should see a validation error:
  """
    Body cannot be blank
  """

You can imagine the steps that Cucumber would use, they’d use the Capybara methods just like the original example.

The point is, this test is testing the user’s interaction with the page, which I think is the most critical part of the application. If the user cannot see this error message, why does it matter if the model validates the presence of this field? It doesn’t.

Testing that the model contains the validation is a secondary thing, and is generally something I skip doing. The test for at least one of the form’s validations goes into the request spec. If I’m feeling pedantic I’ll write another for the other validations, but I can assume that dynamic_form (the thing that provides error_messages_for is doing the right thing when it comes to its own methods. If one error message is showing up, good chance the others are.

In the case where validation error messages don’t show up then I write a specific test for that inside the request spec before going on to fix it wherever I need to.

Testing Complex Logic

In Spree, there’s complex logic involved around orders and tracking inventory. This is something I could test with a request spec, but how the system works is made up of so many little parts it makes it slow to test the whole thing:

• A product exists in the system, has a “count on hand” of 1.
• A user wants to buy this product, so clicks “Add to cart”
• A new order is created in the system, with this item
• User is prompted to sign in
• User is prompted for billing + shipping details.
• User is prompted for credit card details
• User clicks “Confirm” on order page
• Order goes through, deducting 1 from “count on hand” total, bringing it to 0.

A huge portion of these steps aren’t even required to test the count on hand decreasing. What we care about is that when an order is placed in the system that the count on hand decreases by one. And so this is where a unit test would be better.

This unit test would check that when an order is created, a method such as unstock_items! is called. There would then be another unit test for the actual function of the unstock_items! call, ensuring that it goes through the line items for the order and depletes the stock on the products as necessary.

The unit test is going to be much lighter (and quicker to run!) than the request spec, which is just a massive win.

Conclusion

At the final retrospective at the CodeRetreat event on Saturday in Sydney, it was brought up that there’s no “right” way to test. Some people thought that testing from the “bottom-up” (unit test first, request specs or similar later) was better, but then they saw the merits of testing “top-down” (request specs or similar first, then unit tests for the fiddly bits) as well.

I think liberal applications of both of these methodologies is one “right” way to test. The more I test, the more I find myself getting better at knowing what to test and how to test it. I can see the merits of both ways. I’m preferring top-down though, as that’s, in my opinion, testing what the client is going to be seeing, and that’s what matters most. If there’s a bit of gnarly code in there, like the order inventory tracking, then that’s when I’d dive down into unit testing.

What are your thoughts on this?

You may know that I wrote a book. I may have written during the process about the difficulties faced and also about how much it fucking rocks to have a book published. I’ve never felt so damn good for so long.

That’s a topic for another day. Today’s a rant kind of day. Tonight, I feel like shit.

Let the rant begin.

Authoring tools

Let’s start with the authoring tools that Manning provides.

To author a book, you use Manning’s DocBook format, which isn’t actually all that bad once you get used to it. Alternatively you could write in Microsoft Word, but I honestly hate it. The documents just feel… unstructured to me. DocBook appealed to me because I obsess about ordering and structure.

I created all kinds of macros in TextMate for DocBook and was fucking awesome at it towards the end of it. If there were world championships in DocBook, I would place high. Mum would be proud.

Once I had a chapter ready, I had to upload it to Manning’s system. This is done through an SVN repository. I hate (and I mean, truly hate) very few things in this world. Microsoft Word’s one of them, and SVN is another. Years of abuse have me close to suffering post-traumatic stress disorder attacks every time it so much as conflicts on a damned file.

Anyway, once the file’s uploaded to Manning’s system through the version control system from Hell, you get to use the authoring tool also from the same locale. I shit you not, this thing takes 4 clicks to update a single chapter. You need to click on the gear icon, click on a chapter, scroll down to the god-damned bottom of the page listing all the revisions EVER for the chapter (for God knows what reason) (p.s. there’s 80+ for some of the earlier chapters, with each revision taking 4 lines of 12pt text) and then click on the radio button for “Latest” (the text next to this field doesn’t trigger it, of course) and then click “Update”.

I got majorly annoyed with this process in about June of last year and created my own system in twelve hours. It’s goal was to a) allow me to publish updates to all the chapters with one command and b) to provide other people with a super-easy way to review the book, and it did both of those things, but it looked like shit. I fixed that with version two, with the help of a friend.

In total, I received ~1,600 notes on the review systems that I built and they contributed back in major ways to the book. Want to know why the book’s so damned good? Not me. I was just the dude who typed things and put in terrible jokesas footnotes. It’s the reviewers. They did all the hard work. Honestly. They read the same chapter again and again and hhounded me about problems. One guy and I even used to chat regularly on Skype.

Those guys rock. Over 30 people contributed something to the book. Could’ve been “missed a comma”, could’ve been “Prototype sucks!”. I love them all.

Manning’s counterpart to this review system also looks like shit, but only allows for the author and Manning staff to have access to the book. On one hand, this is great because it stops the inevitable piracy (which, as far as I know, never happened on my review system), but on the other hand it really sucks because you don’t get reviews of the book as you go along from people outside your little circle.

So yeah, authoring tools are… depressing to use. I don’t think that any publisher has this nailed yet, although I suspect PragProg has gotten the closest to it.

The One True Format (But not really)

When I started writing the book, I was given a choice. You know this already, but let me refresh your memory just in case you dont: it was DocBook or Microsoft Word. I chose DocBook because it’s a lovely structured format.

I also thought “Sure, these guys probably have the tools to convert this into PDF and ePub and Mobi and monetary notes that I can give to people to buy things”.

Man, I can be naïve sometimes.

When we went to review, they went through the XML document with this tool I can’t remember the name of and it seriously messed with my obsessive formatting. I was non-plussed. I asked them to fix it, and they did, which was nice of them. Still, this tool basically crapped all over the XML document.

My review system did not. Notes were kept separate from the content and not stored as fucking metadata inside the document itself. Why did I do it this way? Because it’s sensible. Down the other path lies madness. I know, because I had to live with that.

That was nothing compared with what happened next. To typeset the book they converted the text into a Word document. I don’t know how exactly they did this (but I suspect it involved the C & V keys on the keyboard, along with a bit of Control). Seriously.

So now what we have is Word document copies of each of the chapters. Word’s review system is very lol-worthy itself also. As an author, I only really care about one note at a time, not the gazillion that the editor has left on the page and Word loves to display.

This means that to update a chapter, I need to ask Manning for a copy of the chapter as a Word document, which they’ll email to me, make the fix myself and then email it back to them. Or I use their document management software which was, I’m sure, designed by people who hate their jobs.

Eventually, enough of these changes will be made and there will be the next for a second printing. When that is, not even I know.

So that lovely little DocBook format I got used to, created all the macros and muscle memory for is now toast. My future is Word documents.

Why printing technical books is just a bad idea

See, with printed books, it’s really hard to update them. You may have noticed this if you have a copy of Rails 3 in Action on your shelf and open to any page listed in the Errata. Has yours been updated? No? Neither have the three sitting on my bench right now.

There’s also the problem of this book becoming quickly outdated due to how quickly Rails moves. We actually upgraded the book to Rails 3.1 in May (the book was printed in September), which was practically “danger close” to the printing time. I’m so happy that we got this change in, but I fear for the future.

If the book was kept in a proper, structured electronic format and never printed on dead trees, then we wouldn’t have this problem. We wouldn’t have “Sydney” misspelt as “Syndey” on the back cover because someone could have fixed it and everyone would be happy. Actually, we wouldn’t have had that if someone didn’t do a rush-job on the cover, but people make mistakes. It’s an OK thing to do.

We wouldn’t run into issues like when Cucumber decides it wants to divorce web_steps.rb and it breaks the whole book. You know why? Because we could update the damn thing. We could release a new update every week if we needed to and people would be happy that it’s a constantly improving, amazing book.

But instead, we print to dead trees, disabling us from updating it efficiently and easily and it stagnates within 6 months.

Now that we finally (just this week) have the ePub and mobi formats available for the book. I suspected they had to use the afore-mentioned C+V keys to do these too. Updating these is easy in comparison: alter the source, compile a new version, put it on a server and let people know. Done.

And hey, it would be super easy if the source was DocBook and there was a tool to read that XML and convert it into ePub friendly HTML. But there’s not one in this process.

That’s how tech publishing should be: electronic only. If you want a dead-tree copy, well, I’m sorry, but you’re going to have to print it yourself.

There will be more

Yeah, we probably did fail at creating The Best Book Ever. But that was never the goal. The goal was to create a book that was easy for noobs to read and learn Rails (and to be the best at that).

I think we succeeded, but I also have a ginormous ego.

Yes, there are mistakes but we will fix them. I will do everything in my power to address any and all (reasonable) concerns you have with the book. I want it to be perfect for you.

There will be updates. Even though Manning’s tools are not that great, the people who work there are some of my favourite people in the world. I will work with these wonderful people and we will release a wonderful Version Two.

Promise.

This week’s screencast is a slightly more advanced topic: debugging a wrong argument type Module (expected class) error which was happening inside of the spree_paypal_express Spree extension.

It’s 28 minutes of debugging goodness and you can view it here.

The next screencasts I will do are examples of how to do nested attributes within Rails, covering belongs_to, has_many and has_many :through associations, along with demystifying how nested attributes works within Rails.

Notice anything wrong?

Probably not.

So let’s take away some things until you start thinking it’s wrong. How about we take out that “RDOC_MAIN.rdoc” string – both instances – and we made the version more prominent? We’ll also get rid of the last modified timestamp, as a date is more friendly to people. Making these simple changes, we’ll get this:

Right. That’s a little better now. It’s clearer what the purpose of this page is and when it was last updated. We don’t care that the README is in a file called “RDOC_MAIN.rdoc”, and so we’ve removed it. Simple.

Now what else don’t we need? Well, when we go to the API we’re most likely going to want to find information about the methods provided by Rails. So why have the README there at all? While it’s a good placeholder for the content, that’s all it is: a placeholder. The main focus of the API site should be what we want to do on it: search for things. If you want to read the README, there’s better (and more standard) places for that, quite simply.

With the README gone, we’re going to have this gigantic void of empty, useless space. With this change, the main feature of the API, the searching, is almost hidden up in the top-left hand corner. So let’s make that more prominent.

Is that menu underneath it really useful? It contains an awfully large amount of items in it. Do people really care about that? Isn’t searching for something a much easier way to find it? I’d say so.

So we remove the README, we remove the menu, we make the search more prominent. What are we left with?

The title, the date the API was last updated and a box to search. There’s no mystery to what this box does: it says “Search” on it. It could also say “Search the Rails API”. Anybody should be able to figure out that you can search the API using this box.

But there’s no button! There doesn’t need to be a button, though. When a person searches, it will autocomplete their search and show the matching results from the API. You could even go a step further and weight certain results, so that things like `ActiveRecord::Base`, um, excuse me, ActiveRecord::FinderMethods’s find method appears before ActiveResource::Base.

Further more, you could get a search for “match” to show the routing (ActionDispatch::Routing::Mapper::Base) match method prominently, and the other match (like the one in HTML::Selector) methods less prominently, perhaps in a grey colour instead of black.

Anything wrong with this now? I think not. The API is less confusing and more prominently displays the function that most people use it for.

That’s my vision for the future of the Rails API. I know it probably won’t get to that stage, as there’s large technical hurdles in the way (such as indexing the entire documentation for Rails into a searchable format), but I think that it’s still possible.

So this weekend I dove into some Backbone.js with the help of Joey Beninghove's great Backbone.js screencasts and built this idea. There’s also a bit of the Twitter Bootstrap in use, which makes things pretty.

It’s called Sume and looks like this:

It’s just a proof-of-concept of this Rails API idea, allowing you to search for only a handful of classes and methods at the moment. But it presents it in a neat format.

Ah, and one more thing: it gives you a unique URL for each page, which is something the current Rails API doesn’t do. When you make a request to the link for ActiveSupport::Concern it actually takes you right to those docs. This makes it easy to link it to other people.

While I was there, I was thinking that there’s just so much work out in the world. So many people doing super interesting things. I started to think that perhaps I should take a break from “shotgun consulting” again, but only if I could find one thing that I was super passionate about.

I was courted by so many different companies when I was at GoGaRuco and Strangeloop and while I was in Chicago. Stuff ranging from a joking “Screw those guys, come work for us!” to more serious “We’ll do whatever it takes you get you on board”. You know what’s a really good feeling? Being wanted. It’s so amazing. So thanks to those companies and their employees for their offers.

While I was in Chicago, I got into some serious-type discussions with two companies. One of them was Groupon, where I sat for about a week doing work remotely for RubyX. I think they have an amazing team at Groupon (including people like Bo Jeanes, who I am very good friends with), but it’s a bit too large for what I wanted to do.

On the very same day that these serious-type discussions happened with Groupon, the same kind of discussions started with a slightly smaller company called Spree Commerce. Sean and I started talking about a Community Manager position that he wanted to fill, a position that involves full-time open source work and talking with members of the community seeing to their needs. Spree has $1.1 million dollars of funding, which will go into some pretty exciting projects.

That is precisely the thing I am passionate about: making a product and the community around it better. Spree has a great platform and it will only get better with time.

For instance, we have just undertaken work to move all of Spree's functionality into a namespace. This will be merged back into themaster branch next week. This means that if you want to have a Product model in your application and still want to use Spree’s then that’s entirely possible. I go into more information in this lengthy post on the Google Group about what the namespacing means.

I’m excited to start officially at Spree next week and I wish RubyX all the best for their future endeavours. If you want a crack team people to build your Rails application, RubyX is that team.

This evening, I recorded a 48 minute screencast and how to begin to code a program to do it in Ruby, explaining things as I go along.

You can see the end result on my screencasts repository on GitHub.

Please let me know of any feedback you have on this screencast (i.e. was the keyboard too noisy or did I speak too fast?) or any ideas for future ones you’d be interested in listening to. Ideally, I’d like to do one every week.

You probably already know the story. You have a whole bunch of tests, perhaps hundreds of them, that take multiple minutes to run as a whole and about 32% of the way through one of the test fails. But that’s ok, because you’re running rspec with the --fail-fast option which will make RSpec quit the instant it comes across a failure, right?

Or maybe not. Well, now you know.

Anyway, this one test is testing some piece of obscure, but required, functionality. Whenever you try thinking about when you worked on it – or even if you worked on it – your mind starts going fuzzy and the room starts to spin widdershins. You run the test by itself and RSpec reports this back:

.

1 example, 0 failures

You put on your “Challenge Accepted” face and re-run the tests again, perhaps this time with the --fail-fast option enabled. Sure enough, the test fails again.

Cool story.

Step 1: DON’T. PANIC.

You want to fix this. It’s 5:30pm. On a Friday. The Friday before a long weekend. The very same Friday you promised someone you’d be home early. But That One Test is being a complete dick about things.

However, there’s light at the end of the tunnel: only 32% of the tests need running before the failure is going to happen. RSpec will (as far as I have observed) run the tests in precisely the same order all the time. This means that the other 68% of your test suite can be excluded from the suspect list.

To fix this bug, you’re going to need a list of all the tests that ran before this test. RSpec doesn’t provide this functionality, and so you’re going to have to build it yourself. But it’s easy! Don’t Panic.

Step 2: Build a list of suspects

You know those pretty little green dots / red Fs / yellow stars RSpec prints out? They’re all coming from a part of RSpec called the `ProgressFormatter`. Look, sensible code! If the example passes, it calls output.print green('.'). You probably couldn’t get more sensible than this.

My point is that RSpec uses this as a kind of reporting tool to show you that progress is actually being made. The great thing about this is that you can write your own! With your own tool, you’ll be able to output to a log what specs are being run and then use this as a base list of suspects.

Create a new file called spec/support/spec_logger.rb and put this content in it:

require 'rspec/core/formatters/progress_formatter'
class SpecLogger < RSpec::Core::Formatters::ProgressFormatter

  def example_started(example)
    super
    File.open("specs.log", "a+") do |f|
      f.write(example.location + "\n")
    end
  end
end

What this does is that it inherits the standard green dots, red Fs and yellow stars from RSpec::Core::Formatters::ProgressFormatter and extends it with a bit of functionality that will log exactly what specs are being run during a test run.

To use this formatter in your next (fast failing) test run, run it using bundle exec rspec spec --require spec/support/spec_logger -f SpecLogger --fail-fast.

Once this command completes, you’ll have a list of suspects in specs.log at the root of your project.

Step 3: Find the perp

In this specs.log file you should have a list of specs that have been run just recently, with the final one being the one that is failing mysteriously. Now let’s assume that in the entire test suite there are exactly 100 tests total. With this failure occurring 32% of the way through, it should be failing at the #32 test. This number is important because it’s equally divisible by two.

However, the locations listed in specs.log are going to have duplicate files, and RSpec only allows you to run multiple files at a time, and not multiple locations within multiple files. This list should be culled to only have one line for each file.

Next, the trick is to take one half of these plus the file containing the failing test and run them together. If you take the first 15 tests and run them in an RSpec command like bundle exec rspec spec <file1> <file2> ... <file15> then you’ll be able to see a result.

This is exactly the process git bisect uses, or at least what I think it does.

If these tests are failing with these first fifteen, then the failure is most likely caused by one of those tests. If it’s not, then it’s in the other half. Re-run the test suite with that half and see if you get a failure there.

When you know which half it is, half it again and keep culling down the list of suspects until you have (ideally) two files: the first will be the one that’s causing the breakage, and the second one will be the one containing the test that’s failing.

From there, figure out what test in that first file is causing things to fail. Comment out half the tests, run the two files again. If it passes then it’s in that half, if it fails then it’s not. Keep at it until you’ve distilled it down to the minimum amount of tests possible, which can be as low as two, but there could be a case where two tests in the original file are causing the disruption.

Step 4: Fix it.

This is left as an exercise to the reader. This could be anything, but at least now you know the area where the code is failing.

Once it’s fixed, run the entire test suite again to ensure that everything is peachy.

If it is, congratulations. Go home. Enjoy the weekend.

This is a story, written in several parts, about my flying experience from Chicago back to Sydney this weekend. I found it entertaining living it, and I hope you find it entertaining reading.

I’m sitting at the gate in Chicago airport and I see this 2 year old girl with her mother, and instantly, fear strikes. The little girl is being perfectly innocent, playing with her toys and giggling. She seems like a little angel, but I know better.

Someone has to sit near that girl, and there’s a chance (although relatively low) it’s gonna be me. This fear comes from being… traumatized… by other children screaming on planes while I’ve tried to sleep or kicking the back of my chair. She could be one of those devil children.

So I calm myself down and remind myself of the tiny statistical probability that I’ll be sitting near her. She seemed fine.

We line up for boarding and I am a ways back in the line from the girl and her mother, thinking that would be the last time I would see the two. I get on the plane and look for my seat 68H, keeping my eyes peeled on the strip above the seats with the numbers. I find row 68 easily enough (yay, sequential numbering!) and then I look down.

The fear came back. There they were, the mother and the daughter. And one spare seat. Just for me. On the aisle. I know how cattle who have been led to the slaughter feel like now. I instantly begin to slide down the wonderful spiral of depression (and into my seat), and then went through the 5 stages of grief in quite rapid succession.

Perhaps everything would be ok. The little girl was handed a bag of things to entertain her and seemed pretty enthralled by the prospect of a Toy Story puzzle. No screams, no crying, no yelling. No kicking seats. I had accepted my fate. I was doomed to sit next to the child for the next 14 hours and perhaps sleep not a wink the entire time. I was… strangely actually OK with that.

Then a male air host comes by and says the most beautiful words I have heard in my entire trip:

“Excuse me sir, are you travelling alone?” “Yes.” “Would you like to move down? I have some spare seats over here you are welcome to.”

A choir of angels sung in my head, the clouds covering the Chicago sky vanished and my fear turned to joy. I moved down a couple of rows to and was assigned a block of three seats, just for myself, right in front of one of the cabin dividers of the aircraft. I laughed at the absurdity of the situation: my acceptance of my approaching doom (of having to sit next to a toddler) and then being not only rescued by an air host, but also being given three. Whole. Seats. For me.

So thank you, Taka, from the Cathay Pacific Chicago to Hong Kong 3:25pm flight on the 28th September. Very much appreciated.

Oh, and Cathay Pacific have powerplugs on each seat (even back here in cattle class) and plenty of leg room. I think everything’s going to be alright.

The plane took off and I enjoyed the thought of having three, whole, seats, to myself for the entire flight. After takeoff, I took out my laptop and did some work for a client.

Later on, I got up to go to the toilet and on my way back this stranger says in a thick American accent “Hey buddy, you’ve got that whole row to yourself up there, right?” and I confirm. He says: “Well look, I’ll do you a deal. I’ll give you one hundred dollars if you let me swap my seat here for your row” and he shows me two empty seats (the aisle and the middle seat) back in the plane, about 20 rows back from where I moved to, 10 back from the kid.

I ask, “is anyone sitting in that middle seat?” and he says no, so I say “Deal!”. He opens the overhead compartment, unzips his bag and pulls out a money clip full of bills, about half a centimeter thick. He leafs through them and hands me $100 in American money.

We go back to my seat and I pack up my things. As I do that we chat about where we both come from, what we are traveling for and where we are going. He says he’s going to the Philippines and would love to stretch out and sleep on the plane.

“Pleasure doing business with you!” I say as I move back in the cabin. “Same to you!” he replies.

I take my new new seat, quite pleased that I made $100 by being lucky. I do a bit more coding, watch a movie, take a sleeping pill and promptly pass out, sleeping for about 4 hours.

As we are approaching Hong Kong, the lady captain comes over the PA and says (in an authoritative voice that only captains have. They probably have some kind of school for Captain Voice) “Cabin crew, 30 minutes to landing”.

More than 30 minutes later we are still in a holding pattern, and the captain comes over the PA again: “Good evening passengers, due to the windy conditions caused by the typhoon in Hong Kong, the Hong Kong airport is backed up and so we are delayed. We apologize for the delay”. At this point, I didn’t know there was a typhoon in Hong Kong. This was also the first time I had ever heard a pilot say “windy”. I guess typhoons are kind of like that.

So we hang about in the holding pattern for about 40 minutes more. “This is the captain again”, the authoritative voice over the PA announces, obviously stressed or annoyed, “we are unable to land in Hong Kong tonight”.

A cacophony of noise starts up. “We are diverting to Taipei airport due to the backup of planes caused by the typhoon over Hong Kong”. I think I giggled a little at this point. This flight just got weirder.

An older guy called Jim sitting one row back over my left shoulder started a conversation with me about our flight and reason for travel, as you do when flying. He was a woodcarver going to the Philippines on a business trip and he spoke about the plight that some of his workers had, having to walk many more miles to get wood due to the deforestation happening there.

As we’re approaching Taipei, the pilot announces “Cabin crew, 30 minutes until landing” again. I had a sense of deja vú at this point, like I had heard her said those exact words before.

But I passed time by talking to Jim about programming, dreams and neural pathways in the brain and we landed alright in Taipei. Everyone on the plane did the usual thing of unbuckling their seatbelts the instant that the seatbelt sign was turned off and they stood up to get out their luggage. Jamming up the aisles with a mass of bodies and luggage.

We waited there for about 20 more minutes without moving. During this time Jim and I talk to another passenger, a teenage boy from Taiwan, on his row who was actually connected to Taipei through Hong Kong and this boy was really happy that the plane had diverted, even if everyone else wasn’t. It would mean that he could just get off here with everyone else, eventually. I certainly wasn’t happy as I had missed my connecting flight out of Hong Kong back to Sydney by that time (the layover was only an hour and a half), and therefore also the breakfast/lunch I had scheduled with some international friends who were arriving at the same time, or near enough.

The captain came over the PA yet again, annoyed still, and said “There’s been a change of plans. We are now in the process of refuelling this aircraft and changing the crew. We are now going to attempt to fly back to Hong Kong and land there. We really apologise for any inconvenience that this has caused you. We will inform you of your options when we get you to Hong Kong.” An American guy behind me sighed loudly and whined that he only wanted to get outside so he could smoke. Long haul flights and smokers aren’t compatible, it seems. He caught a passing flight attendant who quickly dismissed him with a short “no”. He said it was worth a try and continued talking with Jim and I as everyone begun putting their bags back up in the overhead compartment to prepare for the flight back to Hong Kong.

I had wrote the first part (the part about the little girl) of this post on my phone as kind of a short blog post which I thought was an interesting story. I never thought it would turn into this!

So to recap: I’ve been paid $100 to swap seats with a random stranger, missed my connecting flight to Sydney through Hong Kong, met a couple of new temporary airfriends and have no idea when we’re going to Hong Kong or when I will finally get back into my nice, comfortable bed in Sydney. At this stage, it certaintly feels it would be easier just to stay in Taipei on a permanent basis. I hear the people here are nice.

The plane, with fresh crew and unfresh passengers, left Taipei airport somewhere between an hour and two hours after it arrived there and flew back to Hong Kong. We were stuck in the holding pattern again and the new captain, this time a guy, came over the PA: “We’re stuck in a holding pattern over Shenzhen waiting to get into Hong Kong airport. Due to the typhoon, there’s a large number of planes waiting to land in Hong Kong at this time.” mhm. Heard it all before, buddy.

But eventually, we did land. It was just after 1am. As soon as we landed, everyone on the aircraft performed that perfect Pavlovian response to the seatbeat sign again and crowded up the aisles. After a couple of minutes of waiting, the pilot comes over the PA again and says: “Uhh… we currently have nobody to operate the airbridge in the airport. We’re going to be waiting a few more minutes for someone to do that. Please wait.” Massive sighs and a couple of bouts of nervous laughter spread through the cabin.

About 10-20 minutes later we all get off the plane and we are all directed to wait outside the gate, where the crew are giving directions to people who need them. Eventually, we’re lead away from the gate area and down towards the Transfer area in the airport. Along the way, there’s hundreds of extremely-tired looking people who are just sitting on the ground or milling about, waiting for their flights. I had an urge to ask them how long they’d been waiting for, but didn’t ask. That was silly.

What happened next was an utter disaster. I tweeted about my experiences during the whole thing thanks to the free airport wi-fi. Probably the only thing that kept me relatively sane / calm through the entire debacle.

Our “tourguide”, a short, young Asian man, directed us to an empty spot by a shop and told us to wait 20 minutes. He said he needed to go to Head Office to get some clarification on what would happen. We waited for over an hour, perhaps two, and he didn’t come back.

After that, I lined up in one of the impossibly slow lines that looked vaguely like it was going in the direction of the Cathay Pacific desks. Where you would normally expect an orderly queue would flow into an orderly counter area with a 1:1 ratio on clerk to passenger, actually formed into this zombie-mosh-pit of tired travellers. As I was waiting in the line, the Woman and Child came through and actually pushed in front, about 8 people ahead. I was a little angry, but too tired to really care at that stage.

I waited for 3 hours in that line, speaking to various travellers about their plans and backgrounds to keep myself entertained. When I got to the front of the line I actually realised I was also the back of the line. The other people who had been behind me had obviously either pushed in front or had found alternative ways out. The guy behind the counter looked absolutely exhausted and I thanked him greatly for his work. He assigned me a ticket for a flight out of Hong Kong at 9am the next morning, as well as two $40HK vouchers for spending in the airport as a consolation for the flight delays.

I looked around for some seats to crash on but a couple of hundred other people had the same idea as me, so I was relegated to sleeping on the ground which was basically slightly furry concrete. An airline had handed out “consolation blankets” (my name, not theirs), thin airline blankets that people could use if they needed to. I grabbed one and used it as a base.

When I laid down, I noticed two buff black guys near me with deep South African accents were talking. I thought they would eventually fall asleep, and was proven wrong over the course of the next three hours. Every time I tried to fall asleep one of them would laugh or raise their voice and I would be alert again. At about 6:30 I gave up on trying to sleep and listened to their conversation. Surprisingly, they were fashion designers from South Africa. They just didn’t look like the fashion designer type to me.

I rolled out of bed at around 7ish and went upstairs to get some breakfast. I had no idea what exactly my vouchers could buy, so I bought McDonalds as a safety. It was McDonalds, and approximated food well enough that my stomach was not wanting to detach itself and go hunt on its own. Upstairs was packed with bleary-eyed people, probably the same people from the night before who had also missed their connecting flights.

After “breakfast”, I made my way to the gate and set an alarm incase I fell asleep. Thanks to the wonderful sunshine streaming in through the Hong Kong airport there was no chance of that. Eventually 9am came around and I got onto the plane, absolutely tired out of my brain. When I sat down, I felt alright, but later on when I went to the toilet again I looked in the mirror and my eyes were bloodshot and I looked the most tired I had seen myself in years.

The flight back to Sydney was non-eventful, apart from some children on the same row as me playing with the blinds the entire flight, opening them and letting in the “lovely” sunshine while I tried to sleep. Oh, and the absolutely cute Polish chick with the bright-green eyes sitting a row back. But at least I slept. We arrived fine. No holding patterns, no typhoon bullshit, just flying as it should be.

I was overjoyed to arrive at the baggage claim to see my bag there. I was worried that it may have not made the flight, but it seems these airline people know what they’re doing when it comes to planes and things. Surprise!

After catching a cab back home, I took a shower and brushed my teeth. Then I got into bed. Wow. That was such an amazing feeling. I cannot describe it. It had felt like I had wanted, nay, needed to lay in this bed for an eternity and was finally only getting to it. That was kind of the case. 40 hours in-transit is an eternity.

Now I’m back in Sydney and have just about adjusted back to the fact that it has sunshine at the correct times, ready to throw myself back into doing Real Work(tm) and whatever life can throw at me in Sydney.

America was fun and I’m already making plans to go back there again. But probably not this year, as I've got a conference on in the Ukraine I have been invited to speak at in November, and I would like to do a little bit of touring around my own country (Australia) in December. We’ll see.

If you want to learn to code and build stuff and you’re starting by asking someone else what you should do, you’re already thinking about it the wrong way.

I think differently to this person. I think that you should be asking people what you’re doing, but not necessarily just anybody. For instance, you would not ask your grandmother what the latest and greatest changes are in Rails 3.1. You should do some research in the programming language you want to learn and ask those people. IRC channels, Stack Overflow, hell, even find the emails from people in the community and contact them directly. But please do this last part politely and with regard that those people are doing other things as well.

Jared’s post continues on by recommending to Google things:

Go to Google and start asking questions. You want to make a webpage? Ask. You want to know what the different coding languages are and which you should learn? Ask.

Again, I “think differently”. Going to Google and entering “Learn [programming language]” will give you okay results, but they won’t be the best results you can get. This is what the people in the community will be able to tell you better than any search engine that is catering for the masses. For instance, the search engine doesn’t know that you’ve got experience with another language, and so isn’t catering for that. If you tell real, knowledgable people this, they’ll probably recommend something different than if you were, say, a complete newbie to computer programming.

In the first and possibly also for the second case, for Ruby, I would recommend The Well-Grounded Rubyist by David A. Black. It’s a book that teaches you Ruby from the ground-up. Most definitely in the second case I would recommend Learn to Program by Chris Pine. If you read both these books you will gain a solid understanding of Ruby. Promise!

Once you’ve got this basic understanding, then you will know what terms to Google for. Googling right from the beginning, from knowing nothing is akin to googling “Red lump on leg” and expecting it to diagnose your problem. Chances are Google’s going to inevitably lead to a cancer diagnosis. But, if you go speak to an expert in this particular field, like a dermatologist or a doctor at a clinic, they’re going to give you so much better information.

Please, do not Google to learn a language. The way to learn a language is to get your hands on as much reading material / exercises / screencasts that you can, follow the bouncing ball with them and then finally when you feel comfortable, go out and experiment on your own projects. If you break something, so what? Experiment some more and see if you can fix it. Push the boundaries of your knowledge and never, ever be afraid to be wrong, or even to admit it. Then, and only then, when you’re completely stuck on something, ask somebody who knows the language.

Also: ever see a cool feature in an application somewhere? Figure out how it works. Pull it apart and investigate that. You will learn something.

You will only get better with practice and experimentation with the language you want to learn, not basing your knowledge off what Google (of all things!) tells you.

I bought a real bicycle. I blame it for my lack of blog posts and increased fitness levels. I am a nerd, goddammit. I’ve been using to explore Sydney and heckle pedestrians more now that I am not spending weekends writing all the time. In similar news, I’ve lived in Sydney for a year and a half and today was the first day I went to Wentworth Falls. A++, would hike again.

Then there was all this:

Rails 3.1 was released on schedule. Amazing work by amazing dudes. This means that…

I have finished writing Rails 3 in Action and there will be dead trees copies at StrangeLoop conference in St Louis, where I will be in attendance and signing it. (God, that sounds so pretentious.) I honestly don’t think I’ve heard someone say “this is total bollocks” (or something along those lines), but perhaps I am selective of hearing.

You will get your dead-tree copies also when Manning can ship them out. I don’t have any information on these dates at the moment. Updates to the PDF coming shortly, after the typesetters have performed their magic.

I helped out with the now-fantastic Official Asset Pipeline guide that explains the ins-and-outs of the Asset Pipeline with Rails 3.1. Thanks to Mohammad Typaldos, Richard Hulse, and the other people who have worked on it since we first published it on this site.

I begun work on a documentation tool called "Muse", the idea and name I ‘borrowed’ from my co-author, Yehuda Katz and this lets me do things like an internals guide to Sprockets. Muse parses the source file for this guide, validates that it contains correct code examples and then renders it into lovely Markdown.

Ideally, I would like this to work with the Rails guides too eventually, so we could test that its content is still relevant.

Now that the book is done, I will be focussing my efforts on completing that internals guide whenever I find myself with too much spare time and don’t feel like going for a ride or hiking in the mountains.

That was incredibly fun. We should do it again some time. Have your people call my people, we’ll do lunch.

Before all that went down, I created a short (by my standards, anyway) Gist about how the `Sprockets::Railtie` class is currently set up in Rails. This little Gist begun as short note taking for myself and I thought that maybe other people would find the information helpful, so I formatted it all pretty like.

After the battle of the egos took place, I delved a little deeper into the Sprockets rabbit hole, got defeated by some gnarly code and thought “fuck it dude, let’s go bowling to sleep”. I awoke this morning and delved a little deeper into exactly how all of this magic happens.

This guide now lives as the Sprockets Internals Guide on my guides repository. Check out both of them. You may learn something.

So far, it’s looking good. I cover things like:

• image_tag generating a URL such as /assets/image.png which actually is served through Sprockets.
• Assets can be at either app/assets or vendor/assets. No mention of lib/assets because I don’t think it’s sensible to put assets in lib. Maybe someone can explain that one to me.
• By inheriting from Rails::Engine within a gem, that gem’s app/assets subdirectories are now added to the load path for Sprockets. When Sprockets goes looking for an asset, it will look there, providing the directories exist. Also, vendor/assets, ditto.
• Sprockets directives. Not even the Sprockets README, Wiki or site cover this. You would have thought it’s kind of a, you know, core behaviour that people would wet their pants over, but obviously not given the lack of documentation.
• Pre-compiled Sass, SCSS and CoffeeScript and how their relative gems (sass-rails and coffeescript) aid in that purpose, and how they’re served through Sprockets.

But the final thing that I want to cover is how it all works in the production environment. From what I can see, assets are given an MD5 identifier (application.css becomes application-23daf...) for some mysterious purpose and they are cached somewhere. So I went looking for information that explains it. Surely Sam Stephenson or someone else who’s worked on this amazing new core feature for Rails 3.1 has written something about it.

Right?

No. This is a feature that has been packed into Rails 3.1 with no rationale other than hearsay to back it up. The Rails Core team deemed it would be a fabulous idea to have an asset manager within Rails 3.1, and boom, there it was. I’m sure they would have gone with Jammit if only it had been created by a 37signals employee. Oh well, at least Sprockets is.

Jammit is exceptionally well documented and has a group of people who are already using it. Again, this whole rationale business comes into play. There’s no clearly laid out rationale why the Rails Core Team chose to go with Sprockets rather than Jammit. We can circulate rumours and hearsay (like the one above about it being made by a 37signals employee being the reason it was picked) all we like, but it’s not until there’s an actual official piece of documentation that says “this is why things are the way they are” that we are (usually) satisfied.

Bundler’s site is a fantastic example of great documentation. Hell, it even provides a rationale that explains how it works and why it works in pretty easy-to-understand terms.

[breath]

So where do people who want to know about Sprockets go to learn about the rationale of why it is bundled with Rails 3.1? How about the location of any documentation about how to disable it or configure it any way? Well, that was added by yours truly earlier today. I also wrote up some notes just so I could understand how the Sprockets::Railtie works for myself. Thought others may find it useful too.

Not documenting things makes it incredibly hard for anybody else to understand what the hell you’re trying to do and provides no justification for anybody viewing your project as to why they should use it. Any single person can throw code up online. It takes someone special to make people understand why it’s there and why they should want to use it.

I think it’s great that there’s new features being added to Rails and old ones being reworked. But, I think it’s absolute crap that there’s no go-to source of explaining why these things exist and how they make our lives better. I certainly understand how Sprockets makes my life easier, but someone else might not. I don’t want to have to explain to those people every single time they ask “Why should I use sprockets?” my reason for using it. I want to be able to say “I read this guide link and it really helped me understand it. Perhaps you’ll understand too?”

It’s just so incredibly hard trying to explain something in the book when there’s just no reference material to go by or anybody else to ask.

For without this documentation / reference material, the people in search of it write ranty blog posts. And we don’t want that.

This guide is almost a copy of my older Ubuntu, Ruby, RVM, Rails and You guide, but it's written primarily for Mac OS X.

If you're looking for a quick-n-dirty way, then try Wayne E. Seguin's rails_bootstrap_script which probably gets a version of Rails working for you, albeit with 1.8.7 rather than 1.9.2.

This guide will go through installing the RVM (Ruby Version Manager), then a version of Ruby (1.9.2), then Rails and finally Bundler.

By the end of this guide, you will have these things installed and have some very, very easy ways to manage gem dependencies for your different applications / libraries, as well as having multiple Ruby versions installed and usable all at once.

We assume you have sudo access to your machine, and that you have an understanding of the basic concepts of Ruby, such as “What is Rubygems?” and more importantly “How do I turn this computer-thing on?”. This knowledge can be garnered by reading the first chapter of any Ruby book.

Housekeeping

The first thing we’re going to need to install is XCode, which can be found on the second DVD of your install disks or, alternatively, on the Mac App Store for $5. It’s a big download, so you may want to find the DVDs again. We’re going to need this for the build tools that it installs to install Ruby and other packages.

First of all, we’re going to need to install some package management script so that we can install packages such as Git, MySQL and other things exceptionally easy. The best package management system on Mac OS X for this is homebrew. We can install this by using this command:

ruby -e "$(curl -fsSL https://gist.github.com/raw/323731/install_homebrew.rb)"

Once it’s installed, we’ll be able to install the package for Git by using a simple command like this:

brew install git

We’ll need Git to install RVM as it clones it from RVM's GitHub repository.

RVM

RVM is a Ruby Version Manager created by Wayne E. Seguin and is extremely helpful for installing and managing many different versions of Ruby all at once. Sometimes you could be working on a project that requires an older (1.8.7) version of Ruby but also need a new version (1.9.2) for one of your newer projects. This is a problem that RVM solves beautifully.

Another situation could be that you want to have different sets of gems on the same version of Ruby but don’t want to have to do deal with Gem Conflict Hell. RVM has gemsets for this. This is a feature you wouldn't have if you used the packaged Ruby.

We’re going to use it to install only one version of Ruby, but we can consult the documentation if we want to install a different version of Ruby.

With git and curl installed we’ll be able to install RVM with this command:

bash -s stable < <(curl -s https://raw.github.com/wayneeseguin/rvm/master/binscripts/rvm-installer) 

The beautiful part of this is that it installs Ruby to our home directory, providing a sandboxed environment just for us.

Once that’s done, we’re going to need to add a line to ~/.bashrc file (the file responsible for setting up our bash session) which will load RVM:

echo '[[ -s "$HOME/.rvm/scripts/rvm" ]] && source "$HOME/.rvm/scripts/rvm"' >> ~/.bash_profile 

Then we’ll need to reload the ~/.bashrc file which we can do with this small command:

. ~/.bash_profile

If we run rvm notes we’ll be told the certain things that we need to have installed to install the different versions of Ruby:

Notes for Darwin ( Mac OS X )
    For Snow Leopard be sure to have Xcode Tools Version 3.2.1 (1613) or later
    You should download the latest Xcode tools from developer.apple.com.
      (This is since the dvd install for Snow Leopard contained bugs).

    If you intend on installing MacRuby you must install LLVM first.
    If you intend on installing JRuby you must install the JDK.
    If you intend on installing IronRuby you must install Mono (version 2.6 or greater is recommended).

We’re not going to be using MacRuby, JRuby or IronRuby in this guide so we won’t need to install any of those things. If we have XCode installed we will have everything we need to install Ruby.

Now our Ruby lives will be as painless as possible.

Ruby

With RVM and XCode installed we can install Ruby 1.9.2:

rvm install 1.9.2

This command will take a couple of minutes, so grab your $DRINKOFCHOICE and go outside or something. Once it’s done, we’ll have Ruby 1.9.2 installed. To begin using it we can use this lovely command:

rvm use 1.9.2

Are we using 1.9.2? You betcha:

ruby -v
ruby 1.9.2p136 (2010-12-25 revision 30365) [x86_64-linux]

Or, even better, would be to make this the default for our user! Oooh, yes!

rvm --default use 1.9.2

Now whenever we open a new bash session for this user we’ll have Ruby available for us to use! Yay!

Rails

Now that RVM and a version of Ruby is installed, we can install Rails. Because RVM is installed to our home directory, we don’t need to use that nasty sudo to install things; we’ve got write-access to our own things! To install the Rails gem we’ll run this command:

gem install rails

This will install the rails gem and the other 22 gems that it and its dependencies depend on, including Bundler.

MySQL

If you’re planning on using the mysql2 gem for your application then you’ll want to install the mysql Homebrew package using this command:

brew install mysql

If you’re using Rails 3.0 then you’ll need to specify a 0.2.x version of the mysql2 gem in your Gemfile:

gem 'mysql2', '~> 0.2.7'

If you’re using Rails 3.1, then this line will get it:

gem 'mysql2'

PostgreSQL

If you want to use PostgreSQL instead of MySQL:

brew install postgresql

Then in the application’s Gemfile use the pg gem:

gem 'pg'

Fin.

And that’s it! Now you’ve got a Ruby environment you can use to write your (first?) Rails application in with such minimal effort. A good read after this would be the official guides for Ruby on Rails. Or perhaps the documentation on the RVM site which goes into using things such as gemsets and the exceptionally helpful per-project .rvmrc file. A quick way to generate an .rvmrc file is to run a command like this inside the project

rvm use 1.9.2@rails3 --rvmrc

RVM is such a powerful tool and comes in handy for day-to-day Ruby development. Use it, and not the packages from apt to live a life of development luxury.

Anyway, asset pipelining! So I wanted to add theming support to forem because it’s butt-ugly right now and I can’t design for crap. Have you seen this blog? I wanted to make theming so dead-simple for forem that people just need to put one or two lines in their application and BLAMMO it would work.

I have accomplished this goal tonight, in what was probably about 10 minutes of thinking, experimenting and saying “wow, I can’t believe it works” when it actually worked. To make theming work on forem, it’s as simple as putting this line in your Gemfile (after the forem gem, as it needs to be loaded first):

gem 'forem-theme-base', :git => "git://github.com/radar/forem-theme-base"

This gem is actually its own Rails engine, which means that it gets all the goodies that a Rails engine is bestowed, including the automatic hooks to the asset pipelining. This gem also contains this line:

Forem::Engine.theme = :base

This (obviously) tells forem what theme to use, and can be overriden at your wish if you had multiple themes. I am considering having a settings panel for this in the backend.

To actually style the forum you’ll need to put this line in the layout that forem uses:

<%= forum_theme_tag %>

I would make this happen automatically, but other people may wish to apply their site’s styles to the forum system without having to create another gem, and so I leave this as optional. This little tag generates a stylesheet_link_tag like this:

<%= stylesheet_link_tag "assets/forem/base/style.css" %>

Rails then will know where to serve this from because forem-theme-base is an engine.

Dead simple, and utterly amazing. Rails 3.1 is awesome.

On the last day of Railsconf, a group of us went out to dinner. Somehow, the topic of “The Richest Man Alive” came up and basically the entire evening was spent coming up with hilarious fictional scenarios and repeating the best of them where the Rich guy is asked by his butler “Sherry?” to which he replies “Rather!”, in stereotypical rich-guy fashion.

We had some spare time at the airport on Friday morning and I had this scenario that kept playing in my head and getting more intricate and so I wrote it down on a notepad I keep in my bag with the intention of posting it somewhere on the internet. Little did I know then that I would come up with the brilliant idea of posting it on my main blog. This isn’t my idea, but rather an inspired idea from the awesome conversation we had Thursday night. Thanks guys, you know who you are.

So without further ado, I introduce you to The Richest Man Alive:

Markus, the cleaner for Lord Nelson’s third pool, has just been found floating dead in the pool he was supposed to be cleaning.

Lord Nelson sits in his favourite chair by the fire that his stereotypically named butler, Alfred, has beautifully crafted. The butler stands to the right of the chair, dressed immaculately as can be expected by butlers. They discuss the death of Markus.

“Sherry?”, Alfred asked.

“Rather.”, Lord Nelson replies with his thick British-monarch-but-not accent.

Alfred pours a glass of sherry and hands it to Lord Nelson, who then sips it.

“It’s quite atrocious, really.”, Lord Nelson says.

“The sherry?”, Alfred asks, like a dog who’s being told off by his owner. “My deepest…”

“No no, Alfred, about the third pool. The cleaning lad floating in it?”

“Quite, sir.”

“When did they find him?”

“Yesterday afternoon, while you were golfing on the eastern course, sir.”

“Tragic, really. We’ll never get the smell out.”

“I will endeavour, sir.”

“That would be grand, Alfred. Please do see to his arrangements I believe he was in the 4th bedroom on the 5th floor.”

“Yes sir, you are correct. I will attend to those right away, sir.”

“Where the devil do we find one as … talented as Markus?”

“I do not have a clue sir, although I suspect we may be able to find one and bring him in shortly.”

“I am awfully fond of that idea, Alfred, but do you not remember the fuss Markus put up for the first week?”

“Quite, sir. He complained quite emotionally about his treatment by Boris.”

“Yes, Alfred.”, Lord Nelson replies, sipping his expensive sherry.

“Being pulled off the street and pushed into a limousine would do do that though.”

“I agree, but only in part. Boris does need to learn ‘the soft touch’”

“Rather, sir. I remember my … abduction, fondly.”

“Money fills that void, Alfred.”

“Quite, sir. Quite. Margaret is exceptionally glad to receive your annual letters informing her of my continued survival and exceptional service.”

“Indeed.”

“How should I deal with this, sir?”

“Hmm?”

“The body, in the third pool?”

“Ahh, yes. Get Boris to remove it. I hear he has … experience with these matters.”

“KGB, sir.”

“Yes, yes. Good lad. Do find a replacement, Alfred.”

“For Boris?”, Alfred asks hopefully.

“No, not yet. Just the pool boy. God rest his soul.”

“Will that be all sir?”

“Yes, Alfred.”

“Thank you sir, I will deal with these matters right away.”

Alfred leaves the room, while Lord Nelson finishes his sherry.

I’m currently writing what is the final chapter in Rails 3 in Action and I’m pretty excited about it. It’s the “Alternative Authentication” chapter, Chapter 14. It’s not to say there are 14 chapters in the book… there aren’t. There’s seventeen chapters two, maybe three appendicies. This happens to be the last chapter I have to work on and its number is 14.

When I begun writing the book back near the end of April last year I sketched out the idea of this chapter thinking it would be a good thing to show people because a lot of people seem to struggle (myself included) in setting up alternative means of authentication using OAuth (and OpenID, etc.) providers. I personally had no idea what I was going to do write in it at that point in time, but that’s how I’ve been writing the book thus far and it’s turned out pretty alright I hear.

Then a couple of months ago, OmniAuth came onto the scene. My god, it was like Christmas came early. It claimed to simplify the authentication process of alternative services down to its most basic forms. I distinctly remembering trying it out almost immediately and staring in starry-eyed wonder at the process as it worked seamlessly with Twitter and GitHub. That was back in November and I had other chapters I was working on then, like Chapter 11.

With the final chapters of the book I’ve adopted a “work on whatever you feel like” stance with them, as they aren’t required to be done in any particular order. For example, I did the “Engines” chapter (16) before I did the chapter on “Basic performance enhancements” (15) and “Rack applications” (17). It just so happened that Chapter 14 got left to last.

So I worked on it beginning the middle of last week, implementing basic Twitter authentication and writing a pretty decent first draft of it over the next two days. Then on Friday I accidentally deleted my work for the chapter up to about the 20th line in the document (from somewhere around the 350 range) when I ran one of my publishing scripts over it. I had no backups, and it wasn’t version controlled. I felt like an idiot.

Over this past weekend I’ve re-written all of what I did with Twitter on the Friday night and Saturday (which was a poor day of writing, was too distractable). Sunday morning I revised the section and Sunday afternoon I begun in my attempt to use GitHub. That’s when things stopped flowing.

When I write the book I attempt things in the ticketee application first and then just copy over the working code samples from that into the book. It’s a little bit of a laborious process, but it’s worked so far (I know there’s better ways, I just don’t have the time to do them). When I attempted GitHub authentication using Devise 1.2.1’s OmniAuth (0.2.1) authentication support it told me “Invalid credentials”.

I was incredulous. How could I stuff up something so basic when it worked so well with Twitter? I spent the afternoon calling Devise nasty names both out loud and on Twitter and went to bed early, defeated. I could not for the life of me figure this out.

I awoke after a terrible night’s sleep (the kind you have when the problem is right there and you know the solution is there, but isn’t). I dreamed mostly of code. I awoke feeling strangely refreshed at 6am and did the usual morning things before attempting the problem again.

I made sure I had the absolute latest version of Devise and OmniAuth. I did.

I made sure I was able to create a new GitHub application and duplicate these conditions, both on Ticketee and on a brand new Rails application. I was able to do that too.

I was still utterly convinced it was something Devise was doing. I had pointed my finger squarely at it for the past 9 awake hours and why should I question my opinion then? I wanted to make extra sure, so I tried another brand new Rails 3 application but didn’t use Devise. I used straight OmniAuth (thanks to Ryan Bates' superb Railscast on it) and it still didn’t work.

Blast! My prime suspect was no longer prime, nor a suspect! So it was something to do with OmniAuth then, perhaps. I found an application called `omniauth_pure` which claimed to offer a basic example of OmniAuth authentication. I tried this and…

It worked! The damn thing worked. So what was different? Well, I noticed that they were using an older version of the oa-oauth gem (v0.2.0) where I was using v0.3.0. I suspected a problem had been generated between these two versions, and my finger was then pointed at OmniAuth as being the source of all my trouble.

I cloned git://github.com/intridea/omniauth into the vendor/gems/omniauth folder of my application, update the Gemfile accordingly, and tried it again and it was still broken. Ok, it still looked like an omniauth problem. So I did a git bisect (saviour!) and came up with a commit by none other than Michael Bleigh himself: 72b9b619bbc2a41b61ee4ec108bdfa4dc16838f9.

Aha! This commit bumped the oauth2 dependency and, according to git bisect, that commit is to blame for my source of woe. But it’s not, because it’s innocently bumping a gem version up, it’s actually oauth2.

So my finger now switches for a second time to the oauth2 gem. I clone this into the vendor/gems/oauth2 directory, update the Gemfile and do a git bisect on it. The results indicated a commit that I could blame for all my troubles.

It dutifully changes a small detail, the @token\_param to be the OAuth2 draft 10 specified (in section 5.1.2) “oauth_token” rather than “access_token”. This means that all providers who have updated to this draft specification are now supported by the oauth2 gem but those who have not, like GitHub, are left behind.

Ladies and gentleman, after my long story, let me present to you Exhibit A, direct from GitHub's OAuth documentation:

A keen eye, keener than my own, would notice here that the parameter is not called “oauth_token” as is being supplied by the oauth2 gem now as of the afore-mentioned commit, but rather it’s still called “access_token”.

I submit to you that GitHub’s OAuth 2 specification is broken, but the fix is extremely easy and only GitHub (or a hack to oauth2) can fix it.

That was quite a lot of frustration caused by that one small little detail. This was very fun to track down and the high I got from solving it was well worth it. It’s one of the things I enjoy most as a programmer is solving a difficult bug.

The problem itself won’t be fixed until the OAuth2 specification solidifies or oauth2 hacks around it to support different services calling this parameter by different names.

I’m edging ever closer to finishing Rails 3 in Action with only 3 and a half chapters remaining (_Translations_, Background Jobs, Alternative Authentication and Mounting Rack Applications being the half). I’m hoping to knock them off on the next couple of weeks and then the book will be (besides the appendicies) content complete! Finally.

So I think now is a good time to announce my next book: tentatively called Rails 3.1 in Action. This book will contain the same content as Rails 3 in Action but will be specifically directed at people who are running Rails 3.1 rather than Rails 3.0 and so some of the content will be modified to accommodate these changes. The main changes of this will be the moving of the Engines and Mounting Rack Applications chapters from Rails 3 in Action into Rails 3.1 in Action, basically because Rails 3.0 doesn’t have the necessary features to accommodate the awesome things these chapters do, where Rails 3.1 does. Another change is the updating of Chapter 8 from using Prototype (eeew) to jQuery (yaaaay). If you have bought copies of these chapters for Rails 3 in Action we ask kindly that you return them (the chapters, you can keep the rest of the book) and wait until Rails 3.1 in Action comes out with the updated copies.

Manning, Yehuda, our reviewers and I have been talking about the best way to accommodate the readers who have 3.0 applications as well as 3.1 applications (soon enough, this will be the case) and we have decided the best way is to split it out into another book. Rather than have a 2nd edition released so close to the first edition, we’re going to give this book another name to clearly differentiate it between the original (and quite clearly, the best) Rails 3 book.

The day that Rails 3.1 is released is the same day you can expect to be able to visit your nearest bookshop and purchase this new installment of the Rails X in Action series.

Thanks for your support, purchases, comments and praise so far. It really helps!