Turbulence in the asset pipeline

I was running 3.0.20 for a small website and decided it was time to upgrade to the asset pipeline. I didn't require it for this application, but figured it would be good to get some experience.  I also wanted to set the stage for using Twitter Bootstrap. So I figured this past weekend was a good time.

Upgrading to Rails 3.2 was a cake-walk; upgrading to the asset pipeline was another matter. Here's what happened to me in the hopes that it will help other folks.

 To do the upgrade I:

1. Ran my tests in current app - all green - and made last-minute commits & push to master.
2. Created a new branch (rails32) so that I could retreat to safety if needed (I was about ready to toss the whole thing at one point).
3. Went to Ryan Bates' Rails Casts. First episode: Upgrading to Rails 3.2  followed by Upgrading to Rails 3.1. Great stuff! Rails 3.2 without the asset pipeline was up and running in about an hour and worked like a champ: all tests still green.
4. On to the asset pipeline and another Rails Cast: Understanding the Asset Pipeline. This took a bit more time what with moving things around, but another couple hours or so and ready for testing.
5. Ran my tests in the new app and still green so it was all looking good until I displayed the app live - that was an awful mess:
1. Navigation didn't display in the correct location... it was showing up in code sequence rather than being re-positioned to the top of the page
2. The order of the navigation elements was reversed as was the body display: the left-most columns were displayed on the right, as if someone had done a "reverse" on all the data
3. The link elements were displaying not only the display text but also the link itself. The link_to helper was working fine and the a elements were perfect... it was just the display that was a mess.
4. Text elements were overlapping each other in areas.

After many hours of Googling for answers and invoking the help of my friends on the East Bay Ruby Meetup mailing list, and a key post from Billy, I found the answer... actually two of them.

1. I had to explicitly specify the order of my javascript and css files in the manifest files: application.js and application.css. This meant I stopped using the "//= require_tree ." specification and hard-coded the files I wanted in the order that they had been previously specified. Not only did it get the order right but it also excluded certain elements that were present in the tree that I hadn't been using, such as my jasmine_examples and the myriad of optional blueprint files. That fixed almost everything.
2. Remaining was the bad display of the a elements. I started removing CSS files one at a time and struck pay dirt on the first one: blueprint/print.css. I've been using this one all along but in the new configuration it was causing the problem. As soon as I removed this file from the mix, I was back to my old display and running the asset pipeline. Whew! I don't know why this code was suddenly causing a problem but I'll deal with that later.

So... what did I learn so that hopefully I don't make the same mistake next time? YAGNI

• Beware of global options (i.e., //= require_tree .) when upgrading an existing rails app. It may be great for a new app where there's very little to be included, but the cruft that seems to always collect can come back and bite you.
• As always, take a minimalist approach: include only what you really need and leave the rest for the future
• Consider adding some tests that would identify this kind of display-centric issue. Not exactly sure how to handle this, but I'll probably at least add a negative test so that if this kind of error shows up again my tests will fail.

There's still the question of installing this in production. I'm running on Heroku and I understand that are some issues to be dealt with there but that'll have to wait for another day.