zerosum dirt(nap)

Rdoc.info is now serving up fresh docs using YARD 0.4.0. Doesn’t that new template look nice?

If you’re a Ruby OSS developer and haven’t checked out YARD yet, you really should. It’s easily the best way to generate sexy documentation for your projects and Loren has done a really awesome job with the latest release. The experimental new live docs service (with php.net-style user comments) that he’s testing out is swanky too, and we hope to roll this stuff into Rdoc.info shortly.

In the meantime, you can enjoy the latest YARD features and an updated look and feel. Make sure to add a post-commit hook to your GitHub-hosted project and we’ll automatically rebuild docs whenever you push a new release to your remote. Docs for older versions are maintained as well, and accessible via the usual commit hash url [example].

At NH.rb last night I gave a talk about deploying web applications to the EC2 cloud with Rubber. Rubber is an extension to Capistrano written by Matt Conway that makes provisioning and managing multi-instance EC2 deployments magically delicious [GitHub].

Want to bring up an instant multi-role staging server fully loaded with Apache, Passenger, MySQL, and your Rails app? All gem’d up, migrated, and ready to use? Sure you do. First, sign up for an EC2 account, generate your keypair, and then…

gem install rubber

cd my-rails-project
script/generate vulcanize complete_passenger_mysql
edit config/rubber/rubber.yml

cap rubber:create_staging

It uses a Ubuntu AMI and provisions an EC2 small instance by default. If you added your account credentials and the apt packages and gems you needed to rubber.yml (and provided that there weren’t any unexpected problems), you should now have a fully functional staging server for your web app that you can visit at http://appname.your-domain.com.

Since it’s EC2 you only pay for what you use. What’s more is you can horizontally scale this out with relative ease — breaking out the individual roles to separate instances as needed — and/or add your own custom roles as needed (see the other templates available for examples).

Want to learn more? Peep my slide deck and then check out the Rubber Wiki.

Last weekend I attended the first-ever New Hampshire PodCamp, organized chiefly by my friend Leslie Poston along with a crew of enthusiastic volunteer co-organizers (myself included). I only made it to the second of the two days due to prior obligations but had a good time and enjoyed meeting everyone.

If you’ve never been to a PodCamp (I hadn’t) it’s sort of like a branded BarCamp event that focuses more on how people are using technology — such as podcasting, blogging, social networks, video and music on the web — than on straight-up technical topics. I gave a presentation on Developing Twitter Micro-Apps, which I think was pretty well received.

We talked about why building apps that leverage existing social networks can be advantageous, how you can have fun with it, and how to get going really really quick with easy-to-use Ruby tools like Grackle, Rails templates, TwitterAuth (a Rails engine), Darcy’s BirdGrinder toolkit, and my own simple Retweet / Sinatra recipes. You can check out the slides if you want to learn more.

[ Note: The slides were made with slidedown. Although it’s still a little rough in places, it’s quickly becoming my favorite tool for creating slideshows in plain text. ]

That’s me looking pretty intense, live-coding some Twittery shit during the talk. Because, I’m hardcore like that. Unfortunately I didn’t have anyone record the live-coding portions of the presentation, in which we built a conversation aggregator as well as a simple faux-popularity reporting service. Ah well. Other attendees gave talks on topics as various as building interactive and community television outlets on the web, Facebook app development, film promotion, digital photography, and creating Firefox add-ons.

The event itself was held at the New Hampton school in the middle of nowhere New Hampton, NH, which is about an hour north of Manchester. It was quite isolated but the campus was beautiful and the solitude gave people a chance to get away from everything and kept everyone in one spot, resulting in less distractions and more focus on community. Although I really enjoy urban city-center events a lot — especially when they intelligently integrate other elements of the host city into after-hours events — there’s something really nice about isolated rural events (the first New England Railscamp was another example of this)

As someone who has never been very involved in organizing non-virtual conferences / events before, it was also interesting to observe and assist with the process of venue selection, sponsor lineup, and so on. In short: it’s a lot of work, but the payoff is great if it’s done well. Congrats and a big thank-you to Leslie (and all the other co-organizers) for putting this all together. There’s already talk of scheduling the next one for June 2010.

The results are in for the 2009 Rails Rumble. Check em out and peep the winners. Some pretty impressive stuff for a single 48-hour sprint, right? Right!

I’d like to personally thank all the sponsors, expert panelists, and especially the contestants that made this years contest the best one yet. We’re looking forward to using the feedback we’ve received this year to make the next one even better, and starting to seriously discuss doing some more language/framework-agnostic events too.

But first, we need a little bit of a break :). Some downtime next weekend sure will be nice!

Need to unit test those pesky ActiveRecord observers you’re using? I don’t use em often, but there are times when they’re definitely useful. Fortunately, since AR::Observer leverages Ruby’s Observable module all you have to do is call MyModel.delete_observers in your test setup or before block.

ZombieSighting.delete_observers

Better yet, add the exclusions to your test or spec helper file. Then you can unit test your models comfortably in isolation, and write tests for your observers that look like this:

describe Observer
  before(:each) do
    @obs = ZombieSightingObserver.instance
    @thing = Factory.build(:zombie_sighting)
  end

  it 'should generate a new notification' do
    lambda { 
      @obs.after_create(@thing)
    }.should change(Notification, :count)
  end
end

We wouldn’t want to couple zombie sightings too tightly with notifications, after all, as that might anger them even further (zombies are known to be crazy about SRP).

Michael Bleigh’s TwitterAuth gem is truly full of awesome. It’s a complete OAuth authentication and API access solution for building Twitter apps with Rails. It uses familiar conventions borrowed from the Restful Authentication plugin, too. If you’re building a Rails-based app and you want to allow your users to Sign in with Twitter there’s just no better way to go.

For this particular app, I’m using the dynamic duo of Cucumber and Webrat to whip up integration tests. Since I initially stumbled a little bit when thinking about how to test integrated authentication against an external source like Twitter, I thought I’d doc the solution here in case other people were having the same issue.

Ready? Let’s do it.

Setup

First, install the TwitterAuth gem and use the provided generator to whip up the appropriate facilities. You’ll need to register your Twitter application accounts too. Or you know what? Screw it. If you want to make this super easy on yourself, Mike wrote a really great Twitter app Rails template that does all the setup for you, including walking you through getting the dev accounts. It’s nice, try it out. You’ll be up and writing Twitter apps in no time.

For the rest of this I’m going to assume that you have all of that working, and have installed Cucumber too. Don’t have Cucumber? Install it using RubyGems and then just run script/generate cucumber inside your Rails app.

Authentication Feature

So let’s write a Cucumber feature to test authentication in our boilerplate Twitter template application. Put the following in features/authentication.feature:

Feature: Authentication
In order to create and edit games
As a user
I want to sign in with Twitter

  Scenario: Login via Twitter
    When I go to "the homepage"
    And I follow "Login via Twitter"
    And Twitter authorizes me
    Then I should see "Logged in as"

  Scenario: Checking login status
    Given I am signed in
    When I go to "the homepage"
    Then I should see "Logged in as"

  Scenario: Log out
    Given I am signed in
    When I go to "the homepage"
    And I follow "Log out"
    Then I should see "Login via Twitter"

Step Definitions

Next, you’ll need to write step definitions to satisfy the missing steps. Do that by creating a file called features/step_definitions/auth_steps.rb. The content of the file should define the following two steps:

Given /^I am signed in$/ do  
  visit login_path
  visit oauth_callback_path
end  

When /^Twitter authorizes me$/ do
  visit oauth_callback_path
end

Fake Style

The secret sauce here is FakeWeb. We’ll use it to fake out responses from the Twitter auth service so that your integration tests stay local (and reliable). Make sure to gem install fakeweb, and add the following to tests/environments/cucumber.rb:

config.gem "fakeweb", :version => ">= 1.2.5"

Now edit Cucumber’s features/support/env.rb file:

FakeWeb.allow_net_connect = false
FakeWeb.register_uri(:post, 'http://twitter.com/oauth/request_token', :body => 'oauth_token=fake&oauth_token_secret=fake')
FakeWeb.register_uri(:post, 'http://twitter.com/oauth/access_token', :body => 'oauth_token=fake&oauth_token_secret=fake')
FakeWeb.register_uri(:get, 'http://twitter.com/account/verify_credentials.json', :response => File.join(RAILS_ROOT, 'features', 'fixtures', 'verify_credentials.json'))

Here we’re stubbing out the interaction with Twitter auth, and responding to all outbound authorization attempts with canned data. Note that this references a fixture file, containing a sample verify_credentials API response from Twitter. You can obtain a copy using curl from the comfort of your terminal prompt (substitute your own username and password):

curl -i -u user:pass "http://twitter.com/account/verify_credentials.json" > verify_credentials.json

And We’re Done

Alright that should do it. Go ahead and run rake features. Everything should be green. And green is good. If you need to write other features that are dependent on a login requirement, you can reuse the same “Given I am signed in” step that we created earlier.

Thanks to b.kocik, whose original post on using FakeWeb to stub Twitter auth was 80% of the solution I needed here.

We opened registration for the 2009 Rails Rumble yesterday. This is the third year in a row that we’re running the contest and it’s sure to be the best one yet. The build weekend is August 22nd-23rd but you need to register this week if you want a seat. If I were you, I’d go register now before it fills up ;-).

In other news, I’ll be presenting at the second Portsmouth Pecha-Kucha Night tomorrow, July 8th. I’ll actually be talking about the creative power of constraints, and describing our experiences organizing the Rumble will be a big part of that. If you’re in town, make sure to check it out. I’ve never done a p-k talk before but it sounds like it’s going to be a lot of fun.

After I pooped out the initial version of rdoc.info a week or two ago, Jeff and I were bullshitting about the kind of stuff we could add to it when he had a bit of an epiphany: “the place for documentation about GitHub projects is on GitHub”. Yes! Of course! Why didn’t we think of that before?

So we registered the “docs” user on GitHub and went about building an extension to rdoc.info based on the GitHub pages platform. As of now, when you enter a project on rdoc.info, it’ll build docs for them locally and also generate a GitHub-themed set and push them to the docs user account pages on GitHub. In fact, you never even have to visit rdoc.info if you don’t want to (although project documentation will continue to be available there). For an example, see Nunemaker’s HTTParty API Docs. Make sure to play with the methods and namespaces buttons in the header.

As far as I know, we’re the first ones to use GitHub pages as an actual “app platform”, which makes me kind of giddy. You can read more about what we did and how we did it over on Jeff’s blog. He deserves most of the credit for this one, including that awesome GitHub YARD theme and more than a fair bit of tricksy JavaScript goodness. Of course, GitHub deserves a lot of credit too, for building an awesome and extensible service. If you run into any issues with the docs stuff (which is still kinda experimental), please report them via the GitHub project. Thanks!

So yeah, I’m headed off to Vegas this weekend for Railsconf 2009. It’ll be my first evar visit to that area of the country, and although it wouldn’t have been my first choice for a conference location, I’m really looking forward to it (also looking forward to a side trip to the grand canyon after the conference wraps).

I hope to see some of you there and I know that everybody says this, but if you see me in the hallways, definitely come say hi and introduce yourself. To be honest, I often feel a bit overwhelmed at conferences and the things I remember most are the people that I meet and the discussions that we have in the hallways, during hack sessions, or over dinner and beers.

While you’re there don’t forget to check out our panel presentation for the Rails Rumble on Wednesday at 4:25. If you’re going to be attending and want to record the presentation for us, please get in touch with me. You would be my personal hero. I’m looking forward to a couple sessions in particular and I’ll likely also be attending the community organizers BoF, as a way to make up for the fact that I’m missing out on the NE User Group Leader Summit tomorrow.

We’ll be staying at the Sahara during the conference and I’ll probably be checking in occasionally on BrightKite if you want to stalk me.

For the past few months I’ve been trying to roll out a 1 or 2-day micro-app every month. Because, why not — it’s fun and refreshing. In February there was tweetdreams, March was Mogo madness (in use at offrails.org), and in April we spent a few days tossing this together.

The this that I refer to in the previous paragraph is Rdoc.info, a simple web service that generates documentation for Ruby libraries that are hosted on GitHub. You can add a new project and it’ll clone the repo from the hub of Git, use YARD to generate rdocs, and then host them for you. So you can read them. Online. Because it loves you.

If you’re the project owner, it’s even better; just add the following simple post-commit hook to your project’s settings in GitHub http://rdoc.info/projects/update and it’ll automatically regenerate documentation for you whenever you push to the remote. So yeah, unlike a random Twitter vanity application, it’s like, actually useful and stuff.

I’ve shown this to a few friends and they’ve had some good suggestions for how to make it more useful. Jeff, in particular, had some really great ideas that we’ve been looking into (more on that later, hopefully). Anyway, I’ve doc’d feature ideas in the project’s GitHub Issues list, and although we plan to get to them sooner or later, I wanted to release it first as-is, in the spirit of “release early, release often”. If you want to help out, the project has been open-sourced in the usual place.

Railsconf is less than two weeks away. I’m pretty excited because this year we’re doing a Rails Rumble panel with a bunch of swell people who developed some pretty amazing things within the compressed event timeframe (48 hours). Winners and other innovators from both the 2007 and 2008 events will be present. The session is called “Starting Up Fast: Lessons from the Rails Rumble” and the point of it is that these guys will be sharing the tips and tricks that let them build great stuff quick with Rails. Hopefully their advice will be applicable to your own startups and hobby projects, in “real life” as well as within the innovation competition atmosphere.

So this is where we need your help. What do you want to ask them about? Project scoping for early and frequent iterations? Essential dev tools and techniques? Finding dependable partners / cofounders? General work habit questions? Inspirational mantras? Anything goes. Please submit your questions via Google Moderator. The event will be recorded and made available afterwards, so you won’t have to be in attendance to get your answers.

Apparently both Extlib and the Mash library, which the latest version of the Twitter gem relies on, both define Mash as a top-level class. This is lame.

It means that if you're building an app that uses the Twitter gem to poll their API, you can't use DataMapper (which relies on Extlib) for your ORM. This is but one example of an affected application, of course (retweet stack trace). Integrity's twitter notification support is another victim. Epic namespacing fail.

So whose fault is this? The Mash library? Extlib? Which came first? Which is more widely used? OMFG fight!

Seriously, who cares? If you're asking yourself these questions you're missing the point.

module Org
  module Zerosum
    module Util
      class CollisionPrevention
        def initialize
          puts "gtfo"
        end
      end
    end
  end
end

Java users, and consumers of other modern programming languages, figured out why namespacing was important a long time ago. In fact, one of the few things I actually liked from the Java world was it's use of hierarchal domain names in packages to ensure class name uniqueness and prevent this sort of ugly namespace collision. It's simple and effective. And yet we don't see a strategy like this in use in Ruby gems all that often. It's not like Ruby doesn't provide us with a mechanism for it; Modules provide a really easy way to accomplish this. So why aren't we taking advantage of it in our libraries?

I don't mean to single out Extlib and Mash in my rant here -- I'm just picking on them because they happen to demonstrate an obvious problem that we've all run into on occasion. Hell, I'm guilty of it too. Anyway, the bottom line is, that if you intend your code to be sucked into someone else's application and reused, please do your best to prevent obvious namespace collisions. It's as easy as A::B::C (or Tld::Domain::Feature::Specification).

Thanks for listening! :)

I’m a little late to the party on this one, but CouchDB sure is the new hotness. We’ve been tossing around an idea for a new project and it’s a great fit for so many reasons. Schema-less? Check. Distributed and fault-tolerant? Yup. Document revision-aware? and it speaks JSON natively via a RESTful API? Oh yes. It’s easy to see why so many people are getting excited about it.

If you’re used to working with relational databases, it definitely requires a bit of mental reprogramming to really grok Couch, particularly when it comes to working with views and designing document relationships without traditional joins, etc etc. It’s powerful stuff, and after working with it just a little bit, I’m pretty enthusiastic, but still feel like I’ve got a ton to learn.

Anyway, in terms of Ruby client interfaces… there are a surprisingly large number of options that’ll make your life easier. Candidates include ActiveCouch, CouchFu, and RelaxDB. There’s also a DataMapper adapter. My personal pick would have to be jchris’s CouchRest library though. The core of it is very simple, modeled around Couch’s own couch.js library. Plus, the ExtendedDocument model stuff gives you most of what you’d want from a traditional ORM through properties, callbacks, validation mixins (lifted from DataMapper), in-line views (think of them as finder/scopes on steroids), attachments, and so on.

Before diving in too deep I figured I’d port a simple project over to Couch in order to familiarize myself with it. So I created a branch of the Retweet project that uses CouchRest instead of DataMapper. Check it out if you want to see how the CouchRest::ExtendedDocument stuff works in a simple project — only one model in this case. It’s quite nice. There’s also a CouchDB branch of sinatra-template, if you wanna use that to bootstrap your own ideas.

Btw, if you’re on a Mac, and using MacPorts, make sure to port selfupdate to the latest and greatest and then port install couchdb-devel to fetch CouchDB 0.9.0. Anything older than that won’t work with CouchRest.

“In brightest day, in blackest night, no feed shall escape my sight!”

Mogo is a small planet-style feed aggregator built on top of Sinatra, leveraging DataMapper and Paul Dix’s supa-fast Feedzirra library for the actual feed processing. It also teams up nicely with [the all-knowing, all-powerful] Sphinx, making feed search a breeze. There’s a working example of Mogo in action installed here.

Source is available on GitHub so feel free to fork away if you’re in need of such a thing. Patches and pull requests happily accepted.

I gave a hands-on introductory talk about Sinatra at last weeks NH.rb meetup. In case anyone is interested, I’m also embedding the slides below. Looks like scribd butchered them a little bit, but you can always download the original set in PPT format or whatever too (follow the link).

As you might expect, my presentation includes a number of borderline awful puns. Probably not as bad as the puns in a typical Git presentation, but still. You have been warned.

A Quick Introduction to Sinatra (NH Ruby)

A full meetup report is available as well. You can find the full source for the sample door prize chooser app that we live-coded during the presentation via GitHub.