Setting Up a Ruby Development Machine From Scratch With OS X Lion

Every so often I like to completely wipe out my computer and start it over from scratch. This isn’t because I particularly enjoy the pain of setting up a system from scratch, but it does come with some advantages:

• You get rid of the stuff you didn’t need.
• You have a chance to try things that came out since you last reinstalled.
• You have a clean install that isn’t choking from years of cruft.

I took it upon myself to perform this task when I upgraded to OS X Lion and thought it would also be a great chance to write one of those “how to get a Ruby development machine going from scratch” posts since that’s what I’d be doing anyway. So here’s the process of how I got my machine set back up to work the way I want it to on Apple’s latest.

Application Avalanche

	Google Chrome has been my browser of choice for the past year or so. I never would have thought I could give up Firebug, but the speed difference was enough for me to learn to love the Web Inspector.
	iTerm2 is new to my roster. I don’t know too much about it other than that it can do split-pane views which is something I love in all of my apps.
	XCode is a big huge download, and while I don’t use the IDE I need the build tools for just about everything else in my dev toolchain.
	Adium is my universal IM client of choice. It’s simple, customizable, and always there when I need it. I roll with the AdiumIcon icon set, the Mnmlsm message style, and the Leopard Sidebar contact list style.
	Mailplane gives me exactly what I want in an email client: the GMail web interface but in its own dedicated application. While the benefits over something like a Fluid window for GMail aren’t necessarily enormous, email is core enough to my daily routine that it was worth a little cash for a little better experience.
	MacVim is my editor of choice although I don’t pretend to be a “real” Vim user. I switched to Vim *solely* because it allows me to edit with split pane windows, and I still treat it more like Textmate than I’d normally like to admit in public. Note: If you’re planning to use ZSH you’ll want to install a snapshot release of MacVim, otherwise it will occasionally hang.
	Growl is an obvious must-have for any Mac user, developer or not.
	Presently and HipChat are my desktop coworker communication tools and I’d be lost without them.
	Alfred is another new addition to my roster, replacing the Google Quick Search Box. I haven’t used it much yet, but I had heard good things so I’m going to give it a go.
	VLC has a well-deserved reputation for being able to play just about everything. If I could remove Quicktime entirely and replace it with VLC, I would.
	Spotify is what I’ve been using the last week or two. I’ve tried both it and Rdio and I’m honestly pretty torn as to which I like more. But let’s be honest, my primary listening point for music recently has been Turntable.fm.
	The Official Twitter App is the client I’ve used since its release. I’m not a power user (and all of the searches that I care about I handle via Twilert so it works well enough.
	Cloud is an extremely useful little app to have for quickly sharing screenshots and files. I use Skitch as well when I need to be able to annotate the shots quickly.
	Adobe CS5 gives me the tools that I need for putting together logos and design assets. I was going to say “and mocking up sites” but since CSS3 I don’t really use Photoshop for mockups that often these days, I just go straight for the markup.

Command Line Commando

Once I had gotten the easy stuff out of the way, it was time to actually set up all of the development tools that I would need to get my machine up and running the way I needed it.

First up is installing Homebrew. Homebrew is without a doubt the simplest and most “it just works” package manager that I’ve used for OS X. Installing it is as easy as:

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

Once Homebrew is installed, we can go on a mad tear of package installation. Here are some of the tools that I set up right away:

brew install wget git redis node imagemagick
brew install postgresql
brew install mongodb

Another new entry for this round, I thought I’d take my coworkers advice and switch to ZSH with Oh My ZSH. Installed like so:

wget --no-check-certificate https://github.com/robbyrussell/oh-my-zsh/raw/master/tools/install.sh -O - | sh

Next up we’ll install RVM so that we can manage multiple Rubies with ease. I’ll also be installing the Rubies that I use on a regular basis and setting the default Ruby to be 1.9.2 since that’s what I’m using 90% of the time.

bash < <(curl -s https://raw.github.com/wayneeseguin/rvm/master/binscripts/rvm-installer )
rvm install 1.9.2
rvm install jruby
rvm use 1.9.2 --default

After that I needed to follow the instructions printed out by RVM to make sure it was working in my shell. Magnificent! Now we’re almost all done with our basic development stack. We need something to run our web apps, and Pow is definitely my favorite nowadays. We’ll also install the powder gem to make it super simple to manage our Pow links.

curl get.pow.cx | sh
gem install powder

Now I’ve got my development tools up and running, but I still need a little bit more out of my editor. Like I said, I’m a training wheels Vim user, so I like to install Yehuda/Carl’s janus to get a good set of Vim plugins that make Rails development super easy in MacVim.

curl https://raw.github.com/carlhuda/janus/master/bootstrap.sh -o - | sh

We’re getting quite close now. The only thing to do before enjoying my new setup is to make it so that I can clone my repositories off of the various services I use. So I followed the GitHub, Unfuddle, and Heroku setup instructions and I was up and running.

Summary

So that’s pretty much it! Everything went pretty much as expected once I actually got a fresh-drive install of Lion working. The biggest pain was waiting for multi-gigabyte downloads like XCode, but leaving them overnight worked well enough to solve that. So for those who are curious, Ruby development is alive and working on Mac OS X Lion. Is there anything in my setup that you’d do differently? Let me know in the comments!

What if Rails Isn’t For Beginners Anymore?

There’s been a lot of controversy surrounding the changes to Rails 3.1. It started with an epic GitHub commit thread and the discussion exploded again in the past few days after What the Hell is Hapenning to Rails and Yehuda’s response thereto. I’m going to address the issue from a perspective that honestly hadn’t even occurred to me until I just said it while in a conversation with some Kansas City Ruby folks after the last meetup: “What if Rails isn’t for beginners anymore?”

Rails gained its popularity on the strength of its simplicity. The 15-minute blog was a shockingly powerful demonstration of what the framework could do, and from there it has gained thousands upon thousands of dedicated developers. But that’s just the thing: now it has thousands of dedicated developers. And these developers are building some of the most powerful and advanced web apps anywhere on the internet. It’s only natural that as the needs of the community grow so too does the framework. What we may be seeing is a point where Rails is becoming the tool for Ruby web experts instead of Ruby web novices. But if that’s true, is it necessarily a bad thing?

I built RailsWizard as part of the Rails Rumble last year and I thought it would be a tool that would serve two purposes: help me quickly spin up new apps I’m working on and also serve as a step-by-step guide for novice developers who need to get started building a Rails app. However, two rewrites later RailsWizard is a tool that is incredibly fast for my purposes but almost incomprehensible to anyone who doesn’t know what they’re doing. The tool evolved to focus on power for experts rather than friendliness for novices. Ultimately that’s the decision that has to be made for any tool or website: how much tradeoff are you going to give between making something easy to pick up and efficient for experts?

Since my livelihood depends on being able to rapidly build advanced web applications using Rails, you won’t see me beating the drum to take away power from Rails for the sake of novice ease-of-use. In fact, I’m beginning to wonder if Rails is the wrong place to get people started with Ruby web development anyway. There’s always been the problem of people who are Rails but not Ruby developers because ActiveSupport and the facilities Rails give you can make it hard to know what’s stdlib and what isn’t. If people learned Sinatra first, or if the community rallied around a “slightly more than Sinatra” framework like Padrino for newcomers and built up the requisite tutorials and documentations for 15-minute blogs and other things, then the novices who cut their teeth on those tools can come to Rails when they actually understand the power that Rails gives them as developers. They will understand Rails better because they have begun to stretch the limits of the lightweight frameworks and they need more. Maybe a system like that would make for better Ruby and Rails developers.

I’m not saying that any of this is necessarily true, but I think it’s another facet of the debate that hasn’t been explored yet. Personally I love the changes that have been coming to Rails. The asset pipeline may be the most important addition to Rails since even before 3.0: it is a game-changing piece of technology that has been a long time coming. I think the Rails core team has done an incredible job of pushing the envelope and refusing to remain complacent. And I think that’s important, probably more important even than beginner friendliness. Because if Rails gets complacent, if the core team stops pushing out into the weird and uncomfortable, then five years from now nobody will be using it because something better will have come along. And I like Rails.

Conversations: The Controller Setter Pattern

One of the first things that anyone has to do in an application is assign instance variables in controllers for use in views, etc. This pattern, while dead simple, has a number of possible implementations that each have their aesthetic benefits and drawbacks. At RailsConf I had the opportunity to hash this out with none other than DHH and David Chelimsky, so I thought it might be a good opportunity to represent the different sides in a post.

The Repeat Yourself Pattern

This is where things start out many times, as they likely should. You’re building out your controller for the first time, and you set the instance variable you need in each action:

class WidgetsController < ApplicationController
  def show
    @widget = Widget.find(params[:id])
  end

  def edit
    @widget = Widget.find(params[:id])
  end
end

This method, while very clear, has the obvious problem of being repetetive. What happens when your code isn’t as simple as Model.find? You’re going to run into trouble quickly. So let’s try a few abstractions.

The Getter Pattern (The David Chelimsky Way)

So the simplest abstraction is to do what we normally do when we’re repeating ourselves: define a method!

class WidgetsController < ApplicationController
  def show
    @widget = get_widget
  end

  def edit
    @widget = get_widget
  end

  private

  def get_widget
    @widget = Widget.find(params[:id])
  end
end

This pattern has some obvious advantages over repetition: it’s pretty clear what’s happening while giving us the opportunity to define our finder code in a single location. However, we’re still duplicating a line at the top of each action which has a very slight smell.

Note: I’m attributing this to David Chelimsky because I heard him talking about it when I entered the conversation not necessarily because he prefers it to other methods.

The Helper Pattern (The Michael Bleigh Way)

So how can we better abstract this? Well, we’re going to be accessing this instance variable primarily in the view, so why are we bothering to explicitly set it in the controller? This is the pattern that I have been using for the last couple of years:

class WidgetsController < ApplicationController
  def show; end
  def edit; end

  private

  def widget
    @widget ||= Widget.find(params[:id])
  end
  helper_method :widget
end

This gives us a helper that we can call from our controller or our view that will lazily fetch the widget when we need it and not before. Personally I like this pattern quite a bit: I think it’s relatively clear and works well in the various ways I’ve used it. However:

1. It’s a little weird that you don’t see it anywhere above your actions. Might lead to confusion, especially in larger controllers.
2. Via DHH: “You’re calling something in the view that depends on params, which is bad.”

The Filter Pattern (The DHH Way)

Finally we get to a pattern that I was aware of, but have avoided because I found it aesthetically displeasing:

class WidgetsController < ApplicationController
  before_filter :set_widget, :only => [:show, :edit]

  def show; end
  def edit; end

  private

  def set_widget
    @widget = Widget.find(params[:id])
  end
end

So why didn’t I like this? Because before_filter seems like it shouldn’t be setting a variable, but modifying things (DHH agreed that before_filter should likely have a different name such as before_action). Also I didn’t like the fact that the code is split up into two places.

However, DHH made a single argument that trumped everything else I had considered: “When it comes to setters, you don’t care about the implementation, but you care very much that you know it’s there.” And it’s true: the filter isn’t doing anything complicated, it’s just setting an instance variable and its function is very clear from its name. So when you think of it that way, using a before_filter actually makes all kinds of sense.

Why so many?

There are other ways of achieving this pattern, even gems such as decent_exposure that can automate much of it. So why isn’t there a standard solution for this extremely common abstraction “baked in” to Rails? Because at a certain point abstracting behavior that is too simple is more complex than simply not abstracting it at all.

Why did so many patterns evolve for doing the same thing? I lay the blame mostly on both the name and syntax of the before_filter method. When something is called a “filter” you expect it to be manipulating, not setting. In addition (to me at least), the :only and :except syntax doesn’t feel right to use in a common case. To me, these keywords ugly up the declaration and should only be used as a last resort.

So what might we do to the Rails syntax to make this pattern a little easier to understand? Here are a few different options I’ve been thinking about:

class WidgetsController < Application
  # Option A
  run :set_widget, before: [:show, :edit]

  # Option B
  before :show, :edit, set: :widget
  before :index, run: :prepare

  # Option C
  before_action :set_widget, only: [:show, :edit]

  private

  def set_widget
    # ...
  end

  def prepare
    # ...
  end
end

Option A adds a new run method to the controller syntax that acts as an “every filter”. You could specify :before, :after, or :around options and either supply a list of actions or :all for all actions. Two downsides to this: The syntax is a little longer for the case where you want the method to run before all actions, and I don’t have a good analog to :except for this option.

Option B takes a different approach and assumes that the arguments are declaring actions instead of methods to run. Here you declare one or more actions (or none for all actions) and you have two options: you can declare a :set key that will call a method called set_value where value is one or more symbols passed into the option, or you can call the :run option which will simply execute methods named as specified. This may seem like an arbitrary design choice, but Rails is full of choices that don’t have specific need but rather guide developers down doing the best practice instead of doing something else. Downsides to this are again a lack of a good :except syntax and it reverses the current Rails assumption of declaring methods with before so would likely have some confusion associated if it were adopted.

Option C Is simply renaming before_filter to before_action. Obviously you would have to alias it (perhaps through the Rails 3.x versions), but eventually before_filter would be deprecated. The word filter simply implies a certain type of functionality rather than accurately describing it as simply a way to execute code before an action.

I’m not saying that any one of these options is better than what’s already available, I just think that it’s interesting that one of the most common patterns in Rails can still have so much difference of implementation around it. The fact that no one “best practice” has become dominant to me implies that there’s some room to explore API changes to point people down a best path. What are your thoughts on the controller setter pattern?

RailsConf To Go: OmniAuth from the Ground Up

I had the opportunity to speak at RailsConf 2011 about OmniAuth, outlining some of the reasoning behind it as well as some current and upcoming features of Intridea’s own “authenticate with anything” middleware. While the session wasn’t video recorded, a little trick I’ve picked up is to run a screencasting program in the background while I present to generate a “poor man’s Confreaks” version of the talk. Well, that’s exactly what I’ve done for OmniAuth: From the Ground Up!

I’m also embedding the slides below for a “click-through” tour of the talk, but there were a few livecoding sections that are only represented in the video form.

I had a great time at my fourth RailsConf and I hope those who had a chance to attend enjoyed my talk. I also want to say thanks to all of OmniAuth’s contributors, they’ve given me the ability to really ratchet up the awesome on the library and I couldn’t have done it without them.

I Heart SASS, But HAML, I’m Just Not That In To You

Emacs vs Vim. iPhone vs Android. Of all of the nerd arguments, none hits closer to home for Ruby developers than HAML vs ERB. Proponents of HAML look at writing HTML as a dirty practice to be avoided at all costs and look down upon “mere” ERB authors. Meanwhile there’s SASS, a language syntactically close kin to HAML and, until last week, one that even rode along inside the HAML gem. HAML abstracts HTML, SASS abstracts CSS. I’m not here to stop you from using HAML if you like it. Go for it. However, I’m tired of having an aesthetic choice that some developers make bandied about as if it were “the only way” to do things.

The Difference Between HAML and SASS

HAML is an abstraction of HTML that allows for terse description of HTML elements in a meaningful-whitespace format. Rather than writing:

<div id="profile">
  <div class="left column">
    <div id="date"><%= print_date %></div>
    <div id="address"><%= current_user.address %></div>
  </div>
  <div class="right column">
    <div id="email"><%= current_user.email %></div>
    <div id="bio"><%= current_user.bio %></div>
  </div>
</div>

You can instead write:

#profile
  .left.column
    #date= print_date
    #address= current_user.address
  .right.column
    #email= current_user.email
    #bio= current_user.bio

SASS, similarly, is an abstraction of CSS that allows for terse description by allowing for nesting and other conveniences. SASS also includes an SCSS format that looks nearly identical to CSS. For SASS, you go from this:

table.hl {
  margin: 2em 0;
}
table.hl td.ln {
  text-align: right;
}

li {
  font-family: serif;
  font-weight: bold;
  font-size: 1.2em;
}

To this:

table.hl
  margin: 2em 0
  td.ln
    text-align: right

li
  font:
    family: serif
    weight: bold
    size: 1.2em

OK, so that’s HAML and SASS. They both accomplish roughly the same thing, right? Not so much. Here are some of the differences between HAML and SASS:

SASS looks a LOT like CSS. CSS is a series of rule declarations that already follows a relatively terse format. SASS simply adds on the notion of meaningful whitespace and nesting of rules to prevent repetition.

HAML is an abstraction, SASS is an improvement. While HAML and CoffeeScript could be (in my opinion) successfully compared (each provides a syntax that some find more pleasant for writing a certain type of textual content), SASS does something that neither HAML nor CoffeeScript can: it provides functionality that is impossible to achieve in the target compiled language. There’s no such thing as a variable, mixin, or function in CSS. SASS provides a thin layer on top of CSS that adds immense power that wasn’t there before. Personally, I like CoffeeScript, but I also don’t mind writing plain Javascript. I doubt I’ll ever again work on a web project where I don’t use SASS, because it is simply too useful to ever be without.

Learnability. If I sat down with a designer who was familiar with CSS, I could teach them SASS in less than an hour. Despite trying a couple times at various points, I still have to constantly defer to the reference when I’m writing HAML. I’m not saying that HAML doesn’t help some people write HTML templates more efficiently, I’m saying that writing your project in HAML simply guarantees a relatively long and obnoxious learning process for every person who needs to work in the views. Maybe you have a small, fixed team that makes that a possibility, but in many (if not most) real-world scenarios wasting time to teach a templating language that is simply a convenient abstraction is not going to be worth it.

Breadth and Scope. HAML works essentially as a subset of the things you can do in ERB. There are some things that HAML simply won’t do (some of these encourage good programming practices, but the statement is true nonetheless). SASS is a superset of CSS; you can do everything you can do in CSS and significantly more. This difference means that SASS will never tie your hands for styling a site but HAML may tie your hands to a specific means of execution in some scenarios. Again, not to say this is always a bad thing, but it’s a true thing.

Freedom of Choice

I don’t really care if you want to use HAML. I actually can understand how, for developers who don’t like writing HTML and CSS (I work on both sides of the development/design fence) it may feel more productive to be able to write things that way. So go for it, use HAML. Just don’t tell me that my choice is inferior. We’re talking aesthetics here, there is no right and wrong.

There are other ways to accomplish the same terseness that HAML provides while generating pure HTML templates, things like Zen Coding or even just judicious use of some more advanced features of your editor of choice.

TL;DR. SASS and HAML solve two completely different problems. Liking SASS doesn’t imply wrongness in disliking HAML. Using HAML is fine if that’s your bag, but don’t act like it’s the only way. It’s just an aesthetic choice.

You Should Be An Open Source Developer

This post is part of a series called Open Source Citizenry in which I discuss ways to eliminate the barriers that developers and companies face to participating in the open source community.

Last week at Red Dirt Ruby Conf, a tweet came through my stream that seemed to fit quite well with what I was already thinking about for my Open Source Citizenry post this week:

<!— http://twitter.com/#!/mperham/status/61459124273168384 —>

<!— end of tweet —>

In last week’s post I tried to give some insight as to why open source is important for companies. This week, I’ll be looking at the other end of the spectrum: why should you, as a developer, actively contribute to open source? For some, the answer to this question feels natural; however, for many developers the idea of contributing to open source can be daunting, confusing, and somewhat frightening.

It Will Help You Land Your Next Job

Are you unsatisfied with your current job? If you are, it’s a great reason to start contributing to open source. If you’re stuck using a language or framework that you don’t enjoy, or a development practice that you don’t believe in, it’s practically imperative that you begin contributing to open source. Why, you ask?

Because the person that is in charge of hiring at the kind of company you really want to work at is going to be looking at an applicant’s open source contributions as a way to gauge talent. The more (good) open source you release, the closer you will be to getting your dream job before you’ve even had an interview.

Open source contributions are a fantastic way to evaluate incoming employees. The very first thing I do when I’m evaluating a potential hire at Intridea is look them up on GitHub. That’s not to say that we don’t hire people who haven’t done much in the way of open source contribution (there’s more to the hiring process than a single factor). However, I can say that I am going to be much more adamant in my arguments to hire a person if I can see the way their mind works from the open source projects they’ve released.

You Will Write Better Code

Open source is open to the entire world. Everyone can see what you’re writing. If you think this doesn’t have an effect on your willingness to take hacky shortcuts, you’re very wrong. Not only does the mere fact that it’s open source make you write your best code, but open source also helps you to think about your problem domain from a wider perspective.

As I released more and more open source projects, I began to have a kind of Spidey Sense for when something would make a good abstraction. When I’m architecting a project I’m already thinking about how certain pieces could be built in a modular way to maximize reusability. Even if these pieces don’t end up getting released as open source they are still useful extractions that get used in other projects down the road. The concept of building code for a community instead of just for an application makes the work more enjoyable.

Reputation is Real

For a software developer there are essentially two paths to extremely enviable positions of respect in the community: either you can be the tech genius behind a multi-billion dollar startup or you can release open source projects that thousands (not millions) of developers find useful. Guess which one is easier to accomplish?

Reputation isn’t just about vanity, either. Sure, it can feel good to have someone say “Oh cool, I’ve used X!” when they meet you, but building a reputation brings real benefits for you:

1. If you love your company, your company is automatically more respected because you’re a part of it if you have a good reputation.
2. You’ll get the chance to meet, talk to, and learn from the people that you respect. Not that these people are otherwise inaccessible, but having your own “known” libraries gives you some common ground to strike up conversations, get input, and become a better developer.
3. It will get you hired at awesome places. See above.
4. You will get help when you want it. If you have a good reputation and embark on a new project you’ll be able to round up volunteers more quickly if you’re a known entity.

It can occasionally feel shallow or awkward (at least to me) to be thinking about and concentrating on my reputation in the community. However, look at it another way: open source reputation is built on real, honest-to-goodness work that is making people’s lives easier. And if you start releasing bad code, guess how long that reputation will stick around? Reputation is simply a measure of the respect that others have for you based on the merits of your code. And that’s not a bad thing.

That Warm Fuzzy Feeling

It just plain feels good to contribute to open source. The rush you get the first time (as an example) your patch is accepted into a major open source project is exciting. Seeing people using and talking about a library that you wrote is awesome. Hearing that some company that you really admire is using one of your libraries internally is amazing.

Open source feels good because it is good. You are offering value to a community of people free of charge, and in return you get to feel good about yourself and enjoy what you’re doing. Don’t be afraid to pat yourself on the back (maybe not too hard) for getting code out there. It’s more than most people do, and even if only ten developers ever find it useful, that’s ten people that saved hours or days of work because of something you did. And that’s a warm fuzzy feeling.

Standing on the Shoulders of 1,000,000 Dwarves

Open source is amazing because it doesn’t rely on the herculean efforts of a single person or even a few people. Open source is about thousands of people contributing tiny useful things that thousands of other people can build upon. It’s not about building the biggest boat, it’s about making the entire ocean rise. Each and every person who contributes to open source is making a difference to the ecosystem as a whole, and the more people that get involved the better the whole system works together. There can never be too many open source developers.

Barriers to Contribution

I think it’s relatively clear to most developers why open source contribution is a good thing. Additionally, I think there is something intrinsic to the developer’s mindset that drives us to crave the scrutiny and the ups and downs of publicly available code. So why doesn’t everyone write lots of open source? Here are a few reasons with my responses:

1. I’m not good enough to release open source. Poppycock! My first open source release was literally forking another project and hacking at it until it did something I wanted it to do that it didn’t do before. I had no idea what I was doing. I still don’t, most of the time, and I’ve released dozens of open source projects.
2. People will think I suck because my code sucks. Nope, people will ignore your project if your code sucks. That’s the worst case scenario. And, to be honest, if you’re solving a problem that other people haven’t solved, they’ll probably use your code even if it sucks. And then they’ll patch it so it doesn’t suck anymore. Wins all around.
3. How do I even do it? It seems complicated. It’s not, especially in the GitHub era. If you want to know how to do something, find a project that does something similar and steal their execution. Just steal and steal from everyone until you understand it well enough to forge your own path.
4. I don’t have enough time! Find a way to make time! Identify a piece of your existing app code that other people would find useful and extract it out. This cuts your open source time down to abstraction instead of creation. Work on open source for half an hour a day. Convince your company to sponsor some open source time for employees. Contribute small patches to the libraries that you use on a regular basis. Where there’s a will, there’s a way.

I could go into detail and examples on each of these points (please feel free to ask me sometime), but the point is that whatever you think is holding you back from contributing to open source, the reality is much less frightening. Your first project will be the hardest to get out the door, but it gets exponentially easier each time after that.

In coming articles in the series, I’ll talk specifically about how to be a good open source user, how to be a good contributor, and how to be a good project owner. But if you only needed a tiny push to start getting involved, hopefully I was able to supply it. Please feel free to discuss anything related to open source contribution in the comments, I’d be happy to lend what knowledge I have to the service of getting everyone more involved!

Open Source Citizenry Series

1. Why Open Source Company Culture is Important
2. Why You Should Be An Open Source Developer

Why Open Source Company Culture is Important

This post is part of a series called Open Source Citizenry discussing ways to eliminate barriers developers and companies face to participating in the open source community.

Earlier this month I had the opportunity to speak at KCRuby about a topic of my choosing. Rather than use the opportunity to put together a trial run of my upcoming Red Dirt Ruby talk, I decided at the last minute to talk about something that’s been on my mind for a long time. While open source participation is higher than it’s likely ever been, I still see so many people too hesitant, confused, or intimidated to enter the open source community and start releasing. So I wanted to give a cheerleader talk about how everyone can and should be contributing to open source. You can see the showoff slides here, but I think the issue is important enough to merit a larger discourse. This is the first post in a series in which I will be writing about how and why every developer should participate in the open source community. First up, I aim to supply developers everywhere with some ammunition to bring open source culture to their company.

Why Open Source Company Culture is Important

Companies have many ways to benefit from an open source culture. While many arguments can be made about the philosophical implications of choosing to contribute to the open source community, at the end of the day philosophy isn’t going to persuade any CEO to adopt open source. The real reason that open source culture is important to a business is because it’s a business decision that can bring many real-world advantages over the proprietary-focused alternatives.

Defining Open Source Culture

There are many degrees of “openness” in a company’s culture, just as there is a whole spectrum of licensing that is considered “open source” but can have vastly different ramifications for downstream users. Personally, I believe that many companies would benefit from embracing open source as a core aspect of their corporate identity. To me, fully embracing open source means changing the default. Rather than building things and thinking “Should we open source it?” the assumption should be that yes, we will open source it unless there are compelling reasons to avoid doing so.

This is a big leap for a company to take, and I don’t think many are there. We recently acquired RefactorMyCode, and rather than simply taking it over and continuing with it as a product we decided to additionally open source it. There aren’t a ton of reasons why open sourcing would necessarily be a huge win for Intridea, but there are even fewer reasons why it wouldn’t be a good idea. It’s a community-oriented project, it doesn’t contain any kind of magic voodoo patentable algorithm, and we can give the public the chance to refactor RefactorMyCode.

It Leads to Better Code

You may run a tight ship when it comes to code quality and you may even have excellent processes in place to ensure that the code that you deliver is well-tested and sanity-checked before it ever reaches production. However, there is simply no review process that can compare to the power of opening up source code to the world at large and letting them take a look. The code quality bump is due to two primary reasons:

1. Developers building things for open source know that anyone in the world can look at the code they’re writing. It will make them less likely to take easy shortcuts at the expense of good code.
2. Other people will start using your code way off the golden path you imagined when you designed it. This will cause your architecture to evolve to be more flexible, useful, and hardened.

I know that in many cases I’ve had to rewrite large sections of a project because the community use cases have revealed a superior architecture that will encompass a broad range of functionality. I then benefit from this architecture when I need a similar solution in the next project I’m working on for my company.

You Get Work For Free

This is probably the most commonly cited advantage of open source: once you build a community, the community gives you free bug fixes and feature updates without you having to code a single line! This is a real advantage, especially when there is a wide-open field for community addition (such as adding new strategies to my OmniAuth library).

Of course, you need to have a workable community involvement process before you can really reap the benefits of contribution. Thanks largely to GitHub, this process has never been easier, but there are still some things to keep in mind that I’ll cover in a later post.

Your Developers Will Be Happier

There’s a real sense of accomplishment that comes from releasing and contributing to open source. It makes your developers feel like they’re giving back, becoming a real member of the development community, and investing themselves more in the craft of software development. The same can be said of encouraging developers to attend local meetups relevant to the field and conferences.

Why do you care about happier developers? Well, every company should care about happy employees, but software development is a black magic mix of science, artistry, and craftsmanship. While some work can be done by “forcing it”, a good deal of that work requires inspiration and passion, something you won’t be getting out of developers that feel stifled and isolated from the development community at large.

You Will Attract Better Talent

If your company becomes known as one that embraces open source and community involvement, you will begin to attract better talent when it comes time to hire. Sure, having a killer product, good benefits, competitive pay, and many more things affect this strongly as well. But the chance to be involved in open source without having to do so by moonlighting is a chance that is very attractive to the kinds of developers you want to have working at your company.

Open source is synonymous with credibility for many developers. The more well known your company is for having great open source, the higher you rank amongst the development community. It really is that simple.

You Will Gain General Technical Credibility

This may be more applicable to service-oriented companies that do consulting, but in some cases your portfolio of open source projects can be the validation your company needs to win a bid for a client. Intridea has won clients before when they check with their technical expert and he or she confirms “hey, I’ve heard of that company, they released X”.

All of these reasons come about because contributing to and participating in the open source community changes the perception of your company for developers, customers, and other businesses alike. While a company that rabidly protects every scrap of its software might be seen as greedy or, well, basically “jerks”, companies that embrace open source foster a general sense of well-being about them that is difficult to define but something that I’ve definitely experienced personally.

The Flip Side: Addressing Arguments for Proprietary Software

So if, as a developer, you’ve just made your pitch to the higher-ups to embrace open source, you might receive any of these as (valid, by the way) concerns about being more “open” as a company.

1. But we’re a software company, aren’t we giving away our most valuable assets? Nope. Well, maybe if you have a completely novel complex algorithm that solves a problem in a game-changing way, but the truth is that most software isn’t some “secret sauce” that can’t be duplicated by competitors. On the contrary, even with high-level tools and environments at the end of the day a good deal of software development is re-inventing the wheel. The more everyone is involved in open source, the fewer wheels have to be re-invented.
2. We’re on a deadline, we don’t have time for open source. This can be one of the biggest challenges to overcome. I’m not going to lie, supporting open source projects does take time and effort. However, think of it as a tradeoff: by putting in some time and some effort to maintain an open source project, you are gaining all of the free hours of community contribution.
3. What if people look at the code and think it’s awful? Well, then you’re learning a valuable lesson about the code quality you’re producing and you’ll probably be able to identify ways to improve it. Open source projects without tests, with brittle “golden-path” architectures, and even well-intentioned projects that are simply tackling a tough domain are probably going to get some flak. But being wrong isn’t nearly as damaging to your company as being ignorant of the practices that you should be using every day.

This post (and this blog series) is more about starting a discussion than providing definitive answers. I’m not saying I know exactly what your company’s needs are, but I do believe that embracing open source will do more good than harm. If you have any questions, comments, or rotten produce to throw, feel free to start some discussion below. Stay tuned for the next post in the series where I’ll be talking about the benefits to individuals in contributing to open source. And if you’re interested in checking out some of the open source work that Intridea has done, hit our Github page.

1. Why Open Source Company Culture is Important
2. Why You Should Be An Open Source Developer

Easy IP Geotargeting with Geokit and MongoMapper

There are several cases in which it might make sense to tailor your app’s content based on a user’s physical location. But asking them directly is a bit of a pain. Luckily, it’s extremely simple to find a user’s location knowing only something you will always know about a visitor: their IP address. Today I’ll walk you through how to use IPs to geolocate your visitors in a Rails application using Geokit and MongoDB’s geospatial indexing with MongoMapper.

First up, you’ll need to add the gems to your application’s Gemfile. I’m assuming you’re using MongoDB as your application’s primary datastore…if not, you may want to look into a third-party geostore such as SimpleGeo or find another way to locate records based on location. In fact, there’s a Rails plugin for Geokit that offers some of these very features for ActiveRecord. You can find it at the same address linked above.

Getting Setup

First you’ll need to add the necessary gems to your Gemfile:

gem 'geokit'
gem 'mongo_mapper', :git => 'git://github.com/jnunemaker/mongomapper.git', :branch => 'rails3'

Next, you’ll want to generate the MongoMapper configuration file for Rails:

rails g mongo_mapper:config

That’s really about all you need to do.

Finding the right “Market”

For the purposes of this tutorial we’re going to assume that you already have a database of the geographical “markets” that you need to target in your application. If you don’t, it’s surprisingly simple to generate one using the same tools we’re using elsewhere, this gist might point you on the way.

So here we assume basically that you have a Market model that contains a location which, when stored in MongoDB, is a two-member array of a longitude and latitude. The model (simplified) might look like this (and would be located at app/models/market.rb):

class Market
  include MongoMapper::Document

  key :name, String
  key :location, Array
end

The first thing you’ll want to do is make a geospatial index in MongoDB. This can be done by adding the following line to your model:

ensure_index [[:location, '2d']]

Now MongoDB will automatically perform the necessary indexing to allow you to query geographically based on the data. Note that MongoDB’s defaults are set up for latitude and longitude so no further configuration is required.

So in the most simple case, what if we happen to know the user’s longitude and latitude already? We should make a method that will find the nearest market to that user in our Market model:

def self.nearest(location)
  where(:location => {'$near' => location}).limit(1).first
end

Well, that’s pretty simple. Using the MongoDB geospatial querying format, we can easily find documents that are close to the specified latitude and longitude and return the first one.

Adding IP Geolocation to the Mix

But I don’t know my user’s longitude and latitude, you say. Not to fear! We can simply modify our nearest method to handle additional cases, in this case that an IP address is passed in:

def self.nearest(query)
  case query
    when Array
      location = query
    when String
      geo = Geokit::Geocoders::MultiGeocoder.geocode(location)
      if geo.lat.nil?
        # Return a default location, the geocoder couldn't find it.
        # How about New York City?
        location = [-73.98,40.77]
      else
        location = [geo.long, geo.lat]
  end
  where(:location => {'$near' => location}).limit(1).first
end

This looks much more complicated than it is (and for everything it’s doing, it doesn’t really look that complicated). Essentially our nearest method now checks the passed value to see if it’s already a long/lat tuple. If it is, it passes that along. If, however, it’s a string (such as '123.455.231.23') then it will use Geokit’s brilliant multi-geocoder to automagically pull a location from the cloud.

Of course, sometimes an IP won’t map properly to a location (such as 127.0.0.1), and so we need a backup plan. In this case, we’re just returning the coordinates of New York, NY (it’s the biggest market in America, so that’s probably your best guess!).

So now we can call Market.nearest([-55,23]) or Market.nearest('123.455.231.23') or actually even Market.nearest('Smallville, KS') (though this is beyond the intended scope of the tutorial) and we will automatically be given the nearest target market.

Making it Railsy

So now that we’ve done the hard part, how do we integrate this into our Rails app? Why, we just add a quick helper to the application_controller.rb:

class ApplicationController < ActionController::Base
  # ...
  protected

  def nearest_market
    @nearest_market ||= Market.nearest(request.remote_ip)
  end
  helper_method :nearest_market
end

And that’s all there is to it! Now in any view in my app, I could easily write something like:

<h1>Welcome, citizen of <b><%= nearest_market.name %></b></h1>

Of course, I can also do many more interesting things, such as find nearby users, or events, or companies, or whatever else my app might need to find.

This is a simple way to make the very first impression that someone has of your application a little bit more personalized. To make your app have a good experience, you should allow people to choose their target market (even without signing up, perhaps by storing it in a cookie), but this is a strong start. So get out there and geolocate!

RailsWizard Reimagined

TL;DR: I’ve rewritten RailsWizard from the ground up to be as fast and useful to developers as possible. You can now also run it through the command line with the RailsWizard Gem.

Last year for the RailsRumble I built a tool for Rails developers called RailsWizard.

RailsWizard allowed people to build a Rails 3 application template step by step, removing a lot of the tedious and repetetive setup that comes with building a new application. However, there were a few problems:

1. There was no way for the recipes to get updated by the community. This was a hoped-for feature but one that didn’t have time to come to fruition within the confines of the contest.
2. I didn’t love the design of the thing.
3. There was too much overhead to creating a recipe. There were multiple pages with multiple steps and it was all too complicated.

RailsWizard v2

So a short time after the rumble I decided to tackle the problems I saw with the site and built RailsWizard v2. This version was all on one page (a major improvement) and featured a dark, gradient-heavy design with some relatively slick “big click target” radio selectors and such.

When it was first released it still didn’t address the community recipe problem (recipes for v1 and v2 were stored in MongoDB so not accessible from the git repo), but still seemed to be an improvement. Push it out, job well done, all that business.

But as time went on I still found myself very dissatisfied. So I added a community-submitted recipes feature via GitHub login that put things into a moderation queue (can’t have arbitrary code running unchecked on your system). But I’m not even sure it ever worked, because no one seemed to pick up on the recipe submission process. I considered this to be mostly a failure.

Today: RailsWizard v3

Here is RailsWizard as it stands today:

I found myself coming upon a weekend with few to no plans and I decided to finally go for the gusto and build the tool I’d always wanted to have in the first place. My focuses for the rewrite were:

1. Fast
2. Configurable
3. Git-backed Recipes
4. A command line version of the wizard

For the interface, I wanted everything to be as fast as possible. Remove as many options as possible to make it the simplest thing that can possibly work. I wanted there to be configuration options for recipes, thinking of the needs for API keys or choices of database for ActiveRecord. I wanted everything to be stored in Git so that anyone could fork, add a recipe, and get it added via pull request. And I wanted to be able to run the wizard from the command line. RailsWizard v3, now public, allows you to do all of these things!

User Interface

I was inspired by (and used) the Isotope library to make filtering through recipes as fast as possible. Recipes, I decided, would be grouped into categories and would also have “exclusivity” in that if you select MongoMapper as your ORM ActiveRecord would automatically become unavilable. I wanted the whole thing to take less than a minute to completely choose all the recipes and generate your template.

Git-Backed Recipes

This took some real thought. I wanted git-backed recipes, but how was I going to store the metadata associated with them? Also, even though recipes would be Ruby code, they would not actually be needed as executable code in RailsWizard itself, only as text. However, I still wanted them to be as accessible and readable as Ruby code as possible. This is when I decided to get a little bit clever.

I wanted to borrow from Sinatra’s clever “in-file template” system to allow for “in-file metadata” for each recipe. I found this blog post that walked through how to read the data afer __END__ in a Ruby file. I didn’t find out until later that this only worked for the file that was being executed and could not really be used in a library setting (whoops!).

Undaunted, I decided on a new strategy: I would simply read in the strategy files as if they were text files, and split on the __END__ statement. Before the __END__ statement would be the code that would be executed for the recipe and after would be some YAML metadata “back-matter”. This actually worked out incredibly well and made it easy and readable to develop new recipes. You can find out more about this part of the library on the wiki. I now feel that it is exceedingly easy for a person to write custom recipes and contribute them back to the RailsWizard Core.

Configuration

It will often be necessary/convenient for recipes to ask for some configuration information about themselves. For instance, if you’re using Hoptoad, you might need an API (or know to install the Heroku) addon. I decided to put together a robust question-driven configuration system that would be as easy as adding something like this to the YAML back-matter:

config:
  - key_name:
      prompt: What is your favorite color?
      type: string

This allows recipe authors to get configuration details in a consistent manner without having to do the heavy lifting themselves. Again, more information about this aspect of RailsWizard is available on the wiki.

Command Line RailsWizard

This for me was the “holy grail” of my goals for RailsWizard. What if, when you wanted to build a new project, it was as simple to run RailsWizard as it was to run rails new. Now that’s possible:

$ gem install rails_wizard
$ rails_wizard new APP_NAME

This will automatically let you type in desired recipes and build a template using the exact same code that drives the web version. It’s all one library so they will be kept easily in sync. This, for me, is a big deal.

Endgame

All of this comes together to build a framework that I hope the community can really expand upon. I would love to see dozens of user-submitted recipes for every library imaginable. As the recipe collection grows there may be new challenges and features needed to support them all, but I believe that RailsWizard now has the proper foundation to encourage such growth.

If you’re a Rails developer and find yourself frequently creating new Rails projects for experimentation, research, prototyping, or even if you only do it once in a while, RailsWizard can save you hours of initial setup and configuration time. It’s all designed to work together seamlessly and without any complex requirements on you as a developer.

For developers who have built their own custom templates before, please try to break them down into RailsWizard recipes! If you look at the codebase you’ll see how easy it is to build them. So what are you waiting for, get forking already!

Edit: One thing that I wanted to make note of is that for this iteration I focused on fast as the motivating factor for the web UI. This means that, as it stands now, RailsWizard is much more friendly for advanced Rails developers looking to speed up the project kick-off process than it is for beginning Rails developers looking for more explanation and help along the way. One of my future goals will be to provide interfaces to make it a great experience for both!

Always Be Releasing

It’s hard to be “on” all the time as a developer. Despite its engineering aspects, I find software development to be a fundamentally creative act, and creativity requires inspiration. Looking back on the times when I’ve felt in a slump, when I just couldn’t get the energy to make the next big push I needed for whatever project I was working on, I came to a simple realization: I burn out when I’m not releasing.

For me, if I’m not releasing something new at a pace of about once a week, my creative fire is slowly fizzling out. It doesn’t really matter what it is; it could be a new open source library, a great (and complete) feature for a product I’m working on, or even just an in-depth blog post. What I need from releasing is the release that it gives me: it gives me license to take a breath, feel satisfied, and let my brain tackle new problems.

If you’re feeling burnt out, take a step back and think about something you can release this week. Then do it. If you’re really burned out, make it something small, maybe even just a Tweeted gist of some interesting code. Release it, feel that satisfaction, and you might just find that you suddenly have the inspiration and energy you needed to get over your harder, more complicated challenges.

When you really think about it, agile development isn’t simply a method for building better software with a tighter feedback loop. Fast iterations and constant releases also serve as an energizing force for a development team, a way to feel that at least something is finished. Perhaps this insight is nothing more than common knowledge, but I know that it’s going to change the way I think about my schedule. It’s not “what am I working on this week” but “what am I going to release this week”. Maybe it’ll help you, too.