opensoul.org by Brandon Keepers

Ruby at GitHub

2013-04-29T23:26:00-04:00

Here’s the video and slides for my recent talk “Ruby at GitHub” at MountainWest RubyConf.

"Siri, add toilet paper to the shopping list"

2013-01-07T09:13:37-05:00

The Reminders app on iOS and Mac has quickly become one of my favorite apps, mostly due to its integration with Siri and the ability to share lists with my wife.

I almost always have my phone in my hand, so no matter how predisposed I am, I can afford to hold down the home button and say, “Siri, add toilet paper to the shopping list”, or “Remind me to turn off the porch light when I get home.”

It hasn’t been added the Reminders iOS app yet, so many people don’t know it exists, but from the Mac app or iCloud.com you can share a list. The list has to be synced with iCloud for this to work.

Reminders is far from perfect, but it’s the only list–paper or otherwise–that I’ve been able to stick with for more than a week. It offers a glimpse of what the future holds for reminder and todo apps—and takes me one step closer to being completely useless without my phone.

Convert a GitHub Issue Into a Pull Request

2012-11-09T11:26:36-05:00

A little-known-feature of the GitHub API is the ability to attach changes to an issue, converting it into a pull request. The hub command, a wrapper around git that makes it more GitHub aware, allows you to easily do this.

hub pull-request -i 384 -b bkeepers:master -h bkeepers:branch-name

-i is the GitHub issue number
-b is the base, or where you want to send the pull request, with bkeepers being the owner of the repository.
-h is the head, or the branch where your changes live.

Update: in the comments, George Hickman suggests: “as long as you’ve pushed your changes and your local branch is tracking your remote you can exclude the -b and -h options!”. Note that you can set up tracking when pushing with git push -u origin branch-name.

I put together a quick (crappy quality) video showing how this works.

My workflow lately has been something like this:

1. Create a milestone in GitHub Issues for the mini-project I am working on
2. Create Issues for the features I can foresee and begin discussions
3. Work on the code for an issue in a branch
4. Push the branch and convert the issue into a pull request with the command above

This workflow is also great for handling bugs, where someone likely opened an issue to report it, you create the fix in a branch, attach it to the issue, and then close it by merging the pull request.

The biggest caveat with this approach is that it does not work well for experimental code. There is not undo button for converting a pull request back into a plain ol’ issue, nor is there a way to replace the pull request with a different one. So if you convert an issue into a pull request, and then decided you don’t like the implementation, you have to close the issue, burying the discussion around it.

Add helper methods to your Rails console

2012-11-09T09:27:04-05:00

If you use the console on your production application with any regularity, then having helpers for your application is a must! I use the console on Speaker Deck often to debug issues processing PDFs. I almost always start by finding a user by their username or a talk by its URL, so I added helpers to make it brainless.

Adding helpers to the Rails 3 console is easy. Define your helper methods in a module in your lib directory.

module SpeakerDeck
  # These methods are included into the Rails console
  module Console
    # Find a user by username
    def u(username)
      User.find_by_username!(username)
    end

    # Find a talk by url, e.g. "holman/how-to-be-sexy-like-me"
    def t(param)
      username, slug = param.split('/')
      Talk.find_by_username_and_slug!(username, slug)
    end
  end
end

Then, in your application.rb file, pass a block to #console that includes your module into Rails::ConsoleMethods.

module SpeakerDeck
  class Application < Rails::Application
    # …

    console do
      require 'speaker_deck/console'
      Rails::ConsoleMethods.send :include, SpeakerDeck::Console
    end
  end
end

Now, when you run rails console, your methods are available.

>> user = u 'bkeepers'
=> #<User id:…>
>> talk = t 'sachag/side-projects'
=> #<Talk id:…>

Abusing Rails I18N to Set Page Titles

2012-11-05T10:22:18-05:00

I got tired of @page_title variables being sprinkled around in controllers and views on Speaker Deck, so I made good use of Rails’ I18n API to define them all in one spot.

My config/locales/en.yml now looks something like this:

en:
  title:
    default: "Speaker Deck - Share Presentations without the Mess"
    account:
      new: "Sign Up"
      show: "My Account"
    categories:
      show: "%{category}"
    likes:
      index: "Presentations Liked by %{user}"
    passwords:
      index: "Password Reset"
    talks:
      index: "All Presentations"
      edit: "Edit %{talk}"
      new: "New Presentation"
      show: "%{talk}"
    users:
      show: "Talks by %{user}"

To make this work, add a #page_title helper method, which looks up the page title translation using the controller and action name.

module TitleHelper
  def page_title
    t page_title_translation_key,
      page_title_context.merge(:default => :"title.default")
  end

  def page_title_translation_key
    :"title.#{controller_name}.#{action_name}"
  end

  def page_title_context
    controller.view_assigns.symbolize_keys
  end
end

The helper also passes all of the instance variables assigned in the controller, so you can use any of those variables in your page title. The only caveat is that we have to define #to_s in order for our model objects to show up properly in the title:

class User < ActiveRecord::Base
  def to_s
    username
  end
end

Now in our layout, we can use our new helper:

<title><%= page_title %></title>

I’m really happy with how this little hack worked out. This almost seems like something that should be in Rails core. Maybe I’ll have to submit a pull request…

Why Hypermedia APIs Matter

2012-10-29T09:36:16-04:00

You have probably heard recent ramblings about Hypermedia APIs, or HATEOAS, and you completely ignored it because it doesn’t seem to matter. Well, I am here to tell you why it matters. Hypermedia APIs are all about building APIs that allow clients to adapt to changes.

Say you build an amazing REST API for your awesome app. People read your API docs and start using it because, well, it’s amazing. Then, your application evolves. You want to change things, but you can’t, because clients are hard-coded to your API docs. You now have 3 options: 1) avoid changing your app, 2) change it and break existing clients, 3) fork your API and maintain two versions while you wait for old clients to update to the new version. All three of these options suck.

You thought you built a REST API by using HTTP verbs and real URLs. That’s not REST. Read Roy Fielding’s rant REST APIs must be hypertext-driven. Roy knows a thing or two about REST; he kinda invented it.

If you want to build APIs that can adapt along with your application, then you need to learn about Hypermedia APIs. Many people are writing great resources about what this hypermedia stuff is all about. I don’t need to duplicate their effort. If you want to learn how to build adaptable APIs, then start with Steve Klabnik’s Hypermedia API reading list.

There is currently a severe lack of example Hypermedia APIs. I am working on the Speaker Deck API and hope to have at least one good example soon.

Load environment variables with dotenv

2012-07-24T00:31:37-04:00

I released dotenv, a handy Ruby gem that makes loading environment variables 100% less painful in development, guaranteed or your money back.

Backstory

I love the emerging practice of storing application configuration in environment variables. It makes it ridiculously easy to keep secure data out of your code repository while still making it available at runtime. But it slightly complicates development. It’s not always practical to set all of those environment variables on your development machine or continuous integration server where you might run multiple projects.

Foreman provides this handy feature of loading variables from .env, which works great for anything that you want to put in your Procfile. But it doesn’t help you when you run your app manually, run a rake task, or open up the console. My co-workers got tired of me saying Works For Me™, so dotenv solves that problem.

Frontstory

For Rails 3 apps, dotenv will automagically load variables from .env into ENV whenever the environment is bootstrapped. For non-Rails apps, it’s a simple one-liner to load .env. Check out dotenv on GitHub for all the gory details.

What's it like to work at GitHub?

2012-06-06T07:11:23-04:00

I have been traveling a lot lately, and everywhere I go, I get this question: What’s it like to work at GitHub? The simple answer: it is amazing!

Is it true that you work on whatever you want?

Yes. On a few occasions, someone may suggest that I check out a project that could use my help, but nobody tells me what to do. Everyone is encouraged to work on something that interests them and also benefits the company.

Our “Director of Engineering” Ryan Tomayko writes:

I don’t scale. If I tell someone what to do and they do it, then what? Do I have to tell them another thing to do? What happens when I have to decide what to do for 20 people?

Actually, you should just just go read his whole post right now. I will wait…

How is that not anarchy?

It is. Anarchy is a system of governance “that goes to lengths to avoid the use of coercion, violence, force and authority, while still producing a productive and desirable society”.

Anarchy works wonderfully in a small group of individuals with a high level of trust. Everyone at GitHub has full access and permission to do whatever they want. Do great things and you earn respect. Abuse that freedom and you violate everyone’s trust.

How do you decide what to work on?

Several people have asked in the comments and on twitter about this, so I though it was worth addressing.

We have the advantage of using GitHub to build GitHub, so we are intimately aware of the strengths and weaknesses. We use GitHub Issues to keep track of bugs and feature requests that we would like to implement. We also have an internal ideas board for grander ideas that don’t fit into one issue. Anyone can post to it and comment.

The founders and other core people certainly help set a vision for where we are going, but we all take responsibility for deciding what to work on.

What if the thing you want to ship does not benefit the company?

Each person at GitHub has the responsibility to sell their ideas to the rest of the company. I quickly learned that if I can’t get anyone else interested in the project that I want to work on, then either I poorly articulated my vision, or more likely, it does not benefit the company. You can still work on it, but you will likely be working alone.

What if someone is not doing their fair share?

Then they feel insanely guilty because they let everyone down. We are all motivated more by our intrinsic desire to create than by carrots and sticks. The joy of shipping is the greatest motivator. Nobody wants to feel like they are not pulling their own weight.

What are your biggest challenges?

There have been a few.

Overcommitment

The Venn diagram of what interests me and what benefits GitHub looks like two circles getting freaky. There are so many amazing things going on and it is tempting to try to be a part of all of them. I constantly overcommit myself and as a result have not lived up to my own productivity standards for the last several months.

Our benevolent leaders recently called on all of us to focus all our time on shipping one thing. Not allowing myself to commit to something until the current thing I am working on has shipped is teaching me to say “no”.

Signal vs. Noise

With almost 80 people, no hierarchy, and so many amazing projects going on, there is a lot of noise. And I mean a lot. For the first few months, I tried to keep up with what all was going on. But I quickly found myself paralyzed. I was spending half my day just keeping up with what my coworkers were thinking and doing.

I have learned to ignore it all unless it is directly related to what I am shipping.

Opinion overload

Talented people with a lot of experience have strong opinions. With experience comes baggage, and we all have baggage. We swear off tools or techniques because they failed in one situation, without realizing it simply was not a good fit for that situation. Now imagine 55 70 80 experienced people all trying to build amazing things together. There are a lot of intense discussions about what tools we should or should not use and how features should or should not work. Most of it is productive, but it can become tiring.

I have learned that nothing solves an argument like a pull request with working code. Working code moves the conversation forward, and changes are made from there. If you don’t like someone’s pull request, then go create your own and lobby for its acceptance.

Compared to what people have to deal with in other work environments, these are all first world problems.

Where will this lead?

My time at GitHub has been the best six months of my career. I absolutely love the service that we are building. But even more than that, I love the company we are building. If GitHub has only one lasting impact on the world, I hope we can inspire other companies to change how they work.

Do you have more questions about GitHub? Feel free to ask in the comments, and I will do my best to answer them.

Releasing multiple gems from one repository

2012-05-30T14:41:13-04:00

When I released qu, I wanted to split the various backends and exception handlers into multiple gems so each gem had the proper dependencies without enforcing all of the dependencies on everyone all the time.

I had to decide between maintaining multiple repositories for each plugin, or releasing them all from the same repository. There are advantages and disadvantages to both, but I decided I would rather start with them in one repository and split them out later if it became a problem.

Several people have asked how I did it. Here’s my secret formula.

Plugin gemspec

For each gem we want to release, we need a gemspec. For example, check out qu-redis.gemspec. Most of the gemspec is standard, but there are a few things I want to draw to your attention.

Since we’ll be releasing multiple gems out of this directory, we need to make sure we get the right files for this gem. You can use whatever criteria makes sense for your project, but for qu-redis it worked out to just grab any file that has “redis” in the name.

s.files = `git ls-files -- lib | grep redis`.split("\n")

We need to make sure that this plugin then depends on a compatible version of the main library. For Qu, I lock each plugin to the exact version. When I release a bugfix, I release a new version of each gem, whether it is changed or not.

s.add_dependency 'qu', Qu::VERSION

Each plugin can and should declare any other dependencies.

s.add_dependency 'redis-namespace'
s.add_dependency 'simple_uuid'

Now we have a gem for our plugin, with its own files and dependencies.

Main gemspec

The gemspec for our “core” library will look a little different. Check out qu.gemspec for the full version. We want to avoid including files from other gems in our project, so first we get a list of those files.

plugin_files = Dir['qu-*.gemspec'].map { |gemspec|
  eval(File.read(gemspec)).files
}.flatten.uniq

We get a list of the files for the gem, and then exclude files from our other gems.

s.files = `git ls-files`.split("\n") - plugin_files

Gemfile

If you’re using bundler for your development dependencies (which you should be), then you probably want to lock the dependencies from your gemspecs without having to redeclare them. We can easily tell bundler about all of our gemspecs.

source :rubygems

gemspec :name => 'qu'

Dir['qu-*.gemspec'].each do |gemspec|
  plugin = gemspec.scan(/qu-(.*)\.gemspec/).flatten.first
  gemspec(:name => "qu-#{plugin}", :development_group => plugin)
end

Rakefile

Lastly, we want to automate the build process by adding build and release rake tasks.

desc 'Build gem into the pkg directory'
task :build do
  FileUtils.rm_rf('pkg')
  Dir['*.gemspec'].each do |gemspec|
    system "gem build #{gemspec}"
  end
  FileUtils.mkdir_p('pkg')
  FileUtils.mv(Dir['*.gem'], 'pkg')
end

desc 'Tags version, pushes to remote, and pushes gem'
task :release => :build do
  sh 'git', 'tag', '-m', changelog, "v#{Qu::VERSION}"
  sh "git push origin master"
  sh "git push origin v#{Qu::VERSION}"
  sh "ls pkg/*.gem | xargs -n 1 gem push"
end

Profit

This has worked out really well so far. All the activity for the project is in one repo, and pushing out a new release is really easy. Win, win!

What's wrong with Cucumber

2012-05-28T11:17:09-04:00

This post has sat as a draft on my computer for well over a year now. I always intended to finish it, but am beyond caring. So I’m just going to publish it in its current form in hopes that it sparks some interesting conversation and avoids beating a dead horse.

Cucumber is a divisive tool. Some people absolutely love it and have an irrational dedication to using it for every single project. Others hate it, either because they haven’t tried it, or tried it on one project and ended up with a steaming pile of sh…step definitions.

I’ve been using cucumber since one of the first few releases. While I have been burned by it on projects, I also have a great appreciation for it.

What’s wrong with cucumber? Technically, nothing. It’s a brilliant tool for creating DSLs to test our applications. The problem with cucumber is YOU: you don’t understand why to use it, when to use it or how to use it. Don’t worry, though, it’s not entirely your fault. Many people are responsible for encouraging you to use it in asinine ways and advertising it as a magical medical formula that will cure all your woes.

Why: understand the purpose

Cucumber is a tool for creating executable feature specifications, a.k.a acceptance tests. We write these tests to ensure that we have working code that meets our requirements. If the tests don’t help achieve that, then don’t write them. For this reason, I rarely write Rails controller tests anymore.

Fairly or not, many have this misconception that you should write your acceptance tests in plain text so that your client or stakeholders can read and write them. It is highly likely that your stakeholders won’t care about cucumber features. They probably won’t read them, and they almost surely won’t write them.

You should use cucumber because it’s a great tool for giving you a vocabulary to think and talk about how your application should work. As a programmer and perfectionist, I easily get mired in the implementation details and forget that the software I’m writing is actually supposed to do something useful. Driving a feature with cucumber helps me first think though how it should actually work and then guides me through implementing it. It keeps me focused on writing the minimal amount of code to make the software work.

Use Cucumber if it will directly help translate required features into working code. If the person doing the programming doesn’t find it helpful, then don’t use it!

When: you don’t always need a DSL

Cucumber is a DSL for creating a DSL for writing acceptance tests. With me so far? In other words, Cucumber helps you create a vocabulary to describe how your application should work.

Some apps require a DSL to describe their behavior, but many don’t. For a large business application with lots of rules and complicated logic, creating a DSL is the only maintainable way to test it. Testing a simple web API is really a lot quicker and easier with RSpec or Test::Unit.

The advantage of using Cucumber over a plain ol’ testing framework is that it forces you to use a limited vocabulary to describe your application. If your application requires an expansive vocabulary to describe its functionality, then don’t use Cucumber

How: the ivory tower

I don’t think people understand why and when to use Cucumber. But what prompted me to write this post is the recent debate over the removal of web_steps.rb, and that brings us to how.

One of the challenges of a programmer is to find the highest level of abstraction that makes sense. Code with too little abstraction is littered with duplication and is too complex to fit in your head. Code that is abstracted too much is too rigid and cumbersome to use. An abstraction should capture only the details that are relevant for the task at hand.

For many apps, the web interface is the right level of abstraction for describing its functionality.

Cliffhanger: this is the state in which I left this article. I’ve created a gist for this article, so if you’d like to finish making the argument, fork the gist and link to your version in the comments.

My Instapaper Strategy

2012-05-27T12:33:36-04:00

tl;dr: I have found a strategy that leads to Instapaper bliss: sort articles by oldest-first.

Instapaper is wonderful. Besides Tweetbot, it is the most used app on my iPad. It is a gorgous app that makes reading so enjoyable. Anytime someone sends me a link that I can’t read in 2 minutes, I save it to Instapaper to save for that glorious Saturday when I just lay in the hammock and read all afternoon. It’s my very own personal New York Times, Wired, and Sherlock Holmes, all rolled into one.

But Instapaper also causes me quite a bit of strife, because that glorious Saturday afternoon rarely comes. I can’t keep up with the backlog. Over the last 2 years, I’ve collected hundreds of long form articles that taunt me every time I open the app. So I typically open it up, read the latest article or two, and then get disgusted by all the amazing things that I don’t have time to read. A better man might be able to simply ignore that backlog, but it drives me insane.

A few months ago, while exploring Instapaper’s settings to find the ideal font (let’s be honest, I was overwhelmed by how many unread articles there were, so I was procrastinating), I switched the default sorting from “newest-first” to “oldest-first”. I don’t think I expected much to change because of it, but it had an interesting side effect.

There are now only about 20 unread articles in my instapaper queue. I haven’t been reading more lately. I’ve actually been reading less. But I’ve been reading smarter. Here are my theories as to why this simple change had such an impact:

We’re all addicted to new. Our brains secret some good endorphines when we’re riding the wave. But new does not always equal better. By showing oldest articles first, the farther I get behind on Instapaper, the less timely the content is. I now spend more time reading “timeless” articles, and I simply delete the ones that are no longer relevant.
The disire for new still exists, and acts as an incentive to keep up to date.
Sometimes I read things I don’t care about simply because I like the person that recommended it to me. But when I’m looking at articles on Instapaper that are 6 months old, I don’t remember who recommended. So I’m more likely to skip stuff that I don’t care about.

It’s a small thing, but I love small life hacks that streamline my life.

Why Our Code Smells

2012-07-12T09:42:49-04:00

Odors are communication devices. They exist for a reason and are usually trying to tell us something. Our code smells and it is trying to tell us what is wrong.

I have been on a quest with a few coworkers to uncover why our code smells. In this talk, I walk through code from projects that I work on every day, looking for smells that indicate problems, understanding why it smells, what the smell is trying to tell us, and how to refactor it.

The Plight of Pinocchio: JavaScript's quest to become a real language

2012-07-25T13:02:31-04:00

JavaScript is no longer a toy language. Many of our applications can’t function without it. If we are going to use JavaScript to do real things, we need to treat it like a real language, adopting the same practices we use with real languages.

This framework agnostic talk takes a serious look at how we develop JavaScript applications. Despite its prototypical nature, good object-oriented programming principles are still relevant. The design patterns that we’ve grown to know and love work just as well in JavaScript as they do any other language. Test driven development forces us to write modular, decoupled code.

Walking

2012-02-03T10:51:17-05:00

I had to answer the question “What inspires you?” for a TEDx application. Every answer to that question sounds cheesy. Here’s my cheesy answer.

I am inspired by walking; steady, continuous forward progress. Fast enough to get where I want to go in time, but not too fast.

Maintaining a fast pace while walking requires enormous concentration on the act of walking. It is extremely difficult to focus on anything else and maintain a fast pace. I only walk fast when arriving at my destination is of the utmost of importance.

Walking slow is often enjoyable, but neglects the fact that the point of walking is to go somewhere. I walk slow when I have a particularly difficult problem to solve, or I only want a slight change of scenery in hopes of inspiration.

Walking naturally requires almost no concentration. It allows me to focus on what is important, adjust my path when necessary, and arrive at my destination in a reasonable time.

I am inspired by progress. I love the continuous process of taking something that is awkward, uncomfortable or even painful and making it incrementally better.

Getting Started with Sublime Text 2

2013-02-12T11:20:14-05:00

I recently switched to Sublime Text 2 from TextMate. I did not love it at first. As it goes with many of the finer things in life, Sublime is an acquired taste. It was not until I paired with a coworker for a few days that I really started to see its power. I have been using it since and have not looked back.

Here are a few tips that made it easier for me to get into it. Thanks to Anthony Garand for providing feedback and contributing to some of these tips below.

Command palette

Think of the command palette as Alfred for your code editor. Quick access to pretty much anything. Pressing ⌘⇧P will bring up the command palette where you can then scroll through a few of the options available to you: snippets, convert case, sort lines, and toggle various interface options.

Package Control

If you feel like something is missing from Sublime, then there is probably a plugin for it. The most essential plugin is Package Control, which allows you to install pretty much anything.

To use package control, press ⌘⇧P to bring up the command palette, begin to type “install”, and select “Package Control: Install Package”. This will bring up a new palette to search for packages. Find your packages and hit enter to install it. You can see in the status bar at the bottom that it is installing. Most packages will just work, but occasionally you might have to restart Sublime for the package to work.

Beat the ugly out of it

I cannot figure out a nice way to say this, so I will just say it: out of the box, Sublime is hideous. We are pompous programmers, so we cannot let that stand.

Update: The new default theme is actually much better. I still prefer the light Soda theme, but it’s no longer a necessity.

Start by installing the Soda UI theme via Package Control. This is not a theme in the syntax highlighting sense, but for the UI widgets in Sublime. Note that when plugins talk about the Packages directory in Sublime, on OS X that is in ~/Library/Application Support/Sublime Text 2/Packages.

Ahh, that is better. But the icon is ugly too. There are several replacement options on dribbble. This one is my favorite, although there is still much room for improvement.

The syntax highlighting theme that comes with Sublime is alright, but everyone has their favorite theme. Mine is Made of Code. You can use any TextMate theme by copying it to the Packages directory and going to “Preferences » Color Scheme”.

Ok, now we can stand to look at it.

Opening a project

Sublime has support for project files, but I do not use them. I prefer to just open projects from the command line. Sublime comes with a command line interface, but you need to add it to your path.

sudo ln -s "/Applications/Sublime Text 2.app/Contents/SharedSupport/bin/subl" /usr/bin/subl

Now you can open a file or directory from the command line.

subl -n ~/blog

I almost always edit from the current directory, so I set up a bash alias.

alias e="subl -n ."

Ok, now we have Sublime looking pretty and our project open.

Customizing Settings

Sublime is extremely configurable, but the configuration is in a few different JSON files that you have to edit by hand. But once you get familiar with them, they are not that scary.

On OS X, go to “Sublime Text 2 » Preferences”.

For each type of setting, Sublime has at least two files: defaults and custom user settings. You edit the User versions to specify the things you are overriding.

File Settings affect the file that you are currently editing. This includes things like your color scheme, fonts…basically, anything related to editing files.
Global Settings affect how Sublime itself behaves, including the UI theme, files to ignore, and window behavior.
Key bindings are…well, key bindings. 614 lines of glorious shortcut keys.

Take time to browse through the defaults to see all the levers and dials you can tweak. Check out my settings.

⌘p is the new ⌘t

⌘p (which is also mapped to ⌘t) brings up the Go To File palette. In addition to giving you quick access to your files, it has several features to allow you quickly jump into your files. After typing the file name, use @ in the palette to jump directly to a specific method. You can also use ⌘r to bring up the palette prefaced with @ to jump to a method in your current file.

You can also use : (colon) in the palette to go to a specific line number, and ^g will open the paletted prefaced with colon to jump to a line in the current file.

Favorite Plugins

Here is a list of some of my favorite plugins. Most of these should be available to install through Package Control. Check them out and don’t forget to browse around Packgae Control to see what else is available. Here is a complete list of packages available.

One more thing

I highly recommend you go over and read the Sublime article on NetTuts+ for many more tips and tricks to integrate into your workflow as you migrate to this new editor.

I started tweeting tips from @sublimetips on Twitter. Tweet your tips mentioning @sublimetips and I will likely retweet them.

Happy Coding!