Garbled

The other day, I was listening to the Ruby Rogues podcast (which I recommend). The episode was number 36, about Ruby Gems and they had Nick Quaranto on as a guest. For those of you who don’t know, Nick is the originator of the whole GemCutter thing which eventually became what is now RubyGems.org. So he knows a thing or two about gems and, in particular, about the servers that host them all. When you type gem install bundler or whatever, RubyGems.org is where it’s (generally) downloading it from.

I digress. At one point, Nick mentioned that he’d like to see more projects using RubygGems.org’s API and specifically one doing something interesting with gems’ change logs. That, I thought, didn’t sound like a terribly complicated app. So I asked him about it on Twitter, and he pointed me to a GitHub Issue on the topic. You can read the discussion for yourself, but the short of it is that no one was working on a site yet (as best I could tell), so I decided to, and over the 3-day weekend, I banged out Changems.

Right now, there’s fake data in the DB just to give an idea of what I’m thinking. The actual task of getting change logs into the app is not even remotely addressed right now. I’m hoping someone else will at least partially solve that problem, since it’s really hairy. How opinionated do you get? How much freedom do you allow an author before you throw out their log? Should you go so far as to parse Markdown and try to retain code samples and such? Should you only accept plain text (like my fake data) and blow off people who want to get fancy? Then there’s the matter of what people want to call the file (or whether they want to put their change log in the README). Anyway, once those questions at least have rudimentary answers and the site has some real data, I’m sure the community will drive whatever change they feel is appropriate.

Right now, the app is based on the idea that each bullet point in a change log for a version stands alone and is an equal peer with the others from the same version. That might be foolhardy. Maybe each version should just have one big block of data for all the changes; if parsing Markdown or allowing a lot of freedom to make subsections or whatever is important to folks, that would probably be the best bet. But I don’t know yet what folks want. So this post is sort of a plea for help, or at least feedback.

Anyway, it’s 3 evenings of work from one rubyist, so I’m hoping to get people’s thoughts on the topic and maybe some pull requests. If you’d like to talk about it, hit me up on Twitter, or open an Issue on the GitHub repo or, you know, leave a comment here. Also, I threw together the current design, but I am not a designer, so I’d love someone with some actual design chops to send me a pull request. So lemme know: Seem useful? Off to the wrong start? Totally boring? Totally awesome?

I have been paying more attention to software design patterns recently. It all started with my noticing the Null Object pattern and the Ruby Rogues talking about Smalltalk Best Practice Patterns. My most recent discovery is of the Parameter Object pattern. Thanks, by the way, to @timtyrrell for telling me the name of it.

As I’ve mentioned before, I’ve been spending some time at work with a search engine. It works sort of like NewEgg’s search in that you might type a string in (“desktop ram”) and then narrow your search by clicking on links in a side bar (DDR3 or Corsair). The search engine in question powers a product called SubjectLin.es (it’s in beta; you can sign up for a free account to try it out, if you like) where you can search for words that appear in an email subject and then further limit by, say, who sent it (“sender”), what kind of email it is (like coupon or receipt, we call it a “tag”) or what business the sender was in (“market”).

To date, I’ve rewritten the search engine a few times and refactored it a few times. It and one other area of the code base are, by far, the most complex bits of the application, so it has gotten it’s fair share of attention. And it’s gotten more recently when an exception brought our attention to something: We don’t have one search engine… we have four. It’s just that they’re all in one class. Finding the email subjects that a user is interested in is not really related to finding the senders who sent them except that the user’s parameters are the same. So I thought what we’d do is factor out our current search object into 4 smaller ones (subject, sender, tag and market) that each centers around the object it’s pulling out of the DB. Besides code clarity, there are some other benefits we get from this modularity, but I don’t want to get into that in this post.

So now we’re faced with the fact that we’ll have 4 objects we want to create that all depend on the same parameters to build themselves. Add to that the fact that we do some fancy Google-style keyword parsing (you can type “some key words sender:Company” and we pull out the company name) and the fact that if the user is interested in limiting by sender, we want to display things differently than if they aren’t. Now, I thought, it looked as if we should have an object just about the user’s search parameters and that each of our search engines should take only that as an argument.

This way, our view (or presenter… whatever) can ask the search parameter object if the user limited based on sender or not. We can build the one object and then pass it to each of the four engines. We can put all the keyword parsing logic into the search parameter object, too. When I had it, it seemed like such a good idea that it had to have been thought of before. And, lo, it is called the Parameter Object pattern. Or, anyway, I think this is a case of that pattern.

What do you think? Is this Parameter Object? Is it something else? Does my example make any sense at all (I honestly have no idea, since I’m so deep in the system; I tried to balance high-level with need-to-know)? Note: as of this writing, none of this is implemented yet. This is all just design work with @marcosacosta, so far. If anything interesting crops up while we’re writing it, I’ll try to remember to update this post.

At work, I’ve been expending a lot of effort on this complicated search functionality where you can enter a search phrase that will full-text search over one model’s fields (we’re using texticle [github], which is awesome) and limit the results by which other models are involved relationally. Sort of like searching Amazon for “green converse” and choosing the “shoes” category.

The object graph behind this is pretty complicated and it’s been a real education in SQL trying to make sure the query that gets generated is both reasonably speedy and right. Several times, I’ve gotten it “working” only to realize I was joining in some table more than once and so either returning some record twice or excluding it when I shouldn’t've or joining all rows against all rows and, thus, making everything pass all constraints. My SQL skill has leveled up several times throughout, though, which has been really awesome. This is mostly because I was hand-writing a lot of the join SQL with table aliases and whatnot.

Example

The other day, I realized that Rails 3 (or, anyway, the 3.1 release candidates, which is what this app is using) will let you do something that earlier versions would not: do a has_many :through relation on another has_many :through. Say you’ve got Departments composed of Employees. Employees work in groups to create Widgets and which, in turn, get Tags. You can do this number:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

class Widget < AR::Base
  has_many :tags
  has_many :employees
 
  has_many :departments, :through => :employees
end
 
class Tag < AR::Base
  belongs_to :widget
 
  has_many :employees, :through => :widget
  has_many :departments, :through => :employees
end
 
class Employee < AR::Base
  belongs_to :widget
  belongs_to :department
 
  has_many :tags, :through => :widget
end
 
class Department < AR::Base
  has_many :employees
 
  has_many :widgets, :through => :employees
  has_many :tags, :through => :widgets
end

Which enables stuff like:

1

Department.joins(:tags).where(:tag => { :id => params[:tag_id] })

The SQL

So, though, since I was hand-writing my JOIN statements before, I’m clearly concerned with what, exactly, it’s going to execute against the database. So I pulled out good ol’ ActiveRecord::Base#to_sql to see. Here’s what I got (edited without all the quoting and with newlines):

1
2
3
4
5

SELECT departments.* FROM departments
INNER JOIN employees ON employees.department_id = departments.id
INNER JOIN widgets ON widgets.id = employees.widget_id
INNER JOIN tags ON tags.widget_id = widgets.id
WHERE tags.id = 3

Hopefully, that query is pretty straight forward and you can see how ActiveRecord has decided how to make all those joins. However, something struck me: I’m joining through with widgets table, but both employees and tags already have widget_id on them. I’d rather have seen something like:

1
2
3
4

SELECT departments.* FROM departments
INNER JOIN employees ON employees.department_id = departments.id
INNER JOIN tags ON tags.widget_id = employees.widget_id
WHERE tags.id = 3

The result set should be the same and it’s slightly faster. In this example, joining through the extra table wouldn’t be a big hit, probably, but if we’ve got more objects all related to Widgets and many are, like Departments, related through some other object, we might be (and in my case often are) joining many more tables, so if we can eliminate middle-man joins, it can have an appreciable effect on the query’s speed.

How We Do It

So it turns out you can make ActiveRecord generate the above SQL. You don’t want has_many :through for the second association. If you do like this:

1
2
3
4
5
6
7

class Department < AR::Base
  has_many :employees
 
  has_many :widgets, :through => :employees
  # has_many :tags, :through => :widgets
  has_many :tags, :foreign_key => :widget_id, :primary_key => :widget_id
end

You can use the same ActiveRecord query syntax from above to generate the second SQL example. It’s a lot of typing, though, so I wondered: Wouldn’t it be awesome if ActiveRecord knew you when you had this matching-middle-man-foreign-key situation in a query and generated the leaner SQL?

I’m not sure if there are pitfalls to this I’m not seeing (especially related to uses outside what I’m doing with it right now), but I’ve started digging around in the Rails source to see where it’s thinking about these kinds of things (led me to lib/active_record/associations/join_dependency/join_association.rb:72 so far). I’d love some thoughts and feedback on these ideas or guidance in my code-diving efforts. I expect I may end up in the Arel source at some point… we’ll see where it takes me.

Recently, I went to RailsConf. I saw a bunch of talks and met some cool people. This is not a RailsConf post-mortem post (if you’re interested, though, I’ve collected some notes from myself and some others here). This post is about what, in retrospect, was probably the best talk I went to (and I went to several really awesome talks). I’ve been mulling over it since I got back, basically, and that seems like a good result from a talk. That talk was Avdi Grimm‘s Confident Code (slides, my notes).

One thing in particular sort of caught at the edge of my thought patterns: The Null Object Pattern. I don’t have a CS degree and so I’m missing a lot of the formal training about design patterns that many programmers have (and, probably, forget), so I’d never heard of it. When Avdi started talking about how ActiveRecord’s try method is a code smell, I was like, “Yes!” I would not say that I hate it, but I have seen several times some line of code that looks like this:

1

@user.try(:posts).try(:recent).try(:first)

I mean… bleh. But I didn’t know a way that looked any better to me, really. Anyway, you can look at the notes and slides to learn about what Avdi says about the Null Object Pattern. I thought it was awesome and so when I went home, I decided to take it for a test drive.

The Test Course

So in a project at work, we have Users and they may or may not have one Subscription. Hopefully, you can picture this complex object graph. Subscriptions may or may not be “current” based on various business rules mostly to do with whether you paid us or not. So, naturally, we have a Subscrption#current? method. But we’re using the User as a sort of presenter for Subscriptions. So you don’t want to call @user.subscription.current?. That’s a code smell. So on User we had this method:

1
2
3

def current?
  subscription.try(:current?)
end

There’s that rascal try. “This,” I thought, “is a perfect spot for that Maybe method from Avdi’s talk.” So I rewrote it thusly:

1
2
3

def current?
  Maybe(subscription).current?
end

W00t, right? Wrong. The accompanying NullObject class looks like this:

1
2
3
4
5
6
7
8
9

class NullObject
  def method_missing(*args, &block)
    self
  end
 
  def nil?
    true
  end
end

That method missing treatment, so handy in avoiding the chain of trys in my first example, is the gotcha. It means that if I have a User without a Subscription for whatever reason, calling User#current? returns an instance of NullObject, which will pass, say, the boolean clause of an if statement.

So, not sure as to whether I’d misunderstood something, was making some dumb mistake or what, I emailed Avdi. He said, basically, “Awesome question. I will answer it in a blog post.” And, lo, he did. Go read that post to see what he said. The comments also have some good ideas.

Noodles

If you read my comment, I said I was going to noodle on stuff and post again. I had more thoughts than it seemed like would fit in a blog comment. Hence this post. So my initial thought was disappointment. It turned out the Null Object Pattern wasn’t as powerful (in Ruby) as I’d hoped, since if you might have something (calling Maybe) the chances that you’ll have some conditional asking a boolean business-rule question about it is not low.

So I thought about how to get around that. You could, for instance, make a more complex method_missing definition that grepped the message name for /\?$/ and returned false. That’s fail, though. It falls down the moment you have something like this:

1
2
3

if Maybe(@posts).empty?
  # Intuitively, you'd expect NullObject#empty? to have put you in here.
end

But then I realized that Avdi was making a higher-level point: since it is not possible to make your own objects look falsey in Ruby, you have to have another solution. Trying to define various question-mark methods on NullObject is trying to untie the knot, but I should be looking for a way to cut it. So it got me thinking: Why the hell to I have Users without Subscriptions, anyway? Shouldn’t User#current? express that business logic clearly, rather than just express the logic that enforces it? Yes. Yes, it should.

We have some Users who are also admins, who have special rights. It’s also conceivable that we could give away a free account for whatever reason. So, really, we want something like this:

1
2
3

def current?
  self.free_account? || subscription.current?
end

But, this thought it incomplete. It expresses the business logic cleanly: The User is current if they’re flagged as free or if their Subscription is up to date. However, if the weird case of a User who is neither free nor has an associated Subscription crops up, we still have to hunt down the “Undefined method ‘current?’ for nil” error. It sort of has be reaching for Maybe again.

Or maybe (heh, you see what I did there) I want to steal another trick from Avdi’s presentation and have User#subscription return :no_subscription_defined_for_user so that the error message makes some more sense. I don’t like redefining ActiveRecord‘s default accessor methods, though, to transparently return the symbol if the real object is missing.

If you’ve got any thoughts, I’d love to hear them.

Holy crap. Did I really start this blog in December 2008? That would make it more than 2 years old. Wow. Well, good on me, I guess. That feels sort of absurd. Anyway…

An Itch…

The other day at work, I had to get the OAuth credentials for a twitter account that our application would use to send programmatic tweets to. For those of you not familiar with OAuth, a brief description: The usual way you OAuth with Twitter is that you have a web page where a user clicks something indicating they’d like to OAuth you to their account. You then send your consumer key and secret off to Twitter to get a request token and, using that, you send the user off to a url over on twitter.com.

Once there, they sign in (or are already signed in) and click “Allow”. Twitter then hits your callback url with some more tokens, which you use to make a final reply and then they respond with the access token and secret you’ll need to do whatever it is you’re doing with the user’s account. If the user changes username or password, you’re still authorized and if they want to revoke your access, they can without changing their username or password. Great! (If you’re thinking, “What?!? Not great! That made no sense!” then maybe the image in this article will help).

However, when your program is a desktop client or when you’ve only got one account you’ll ever be tweeting from (or maybe a small handful), it’s not really practical to build a web interface and a callback url to hit so that you can do the whole dance and get the tokens. So Twitter has an alternate path that replaces the redirects in the middle of the dance. Instead of redirecting users over to twitter.com, you show them the URL and they go there manually. When they click “Allow”, they’re given a PIN, which they then give back to you and you can then finish off the dance as if the PIN were the callback.

…Scratched

So at work, I hacked around in the console for a bit and eventually figured out how to work the PIN-based method, ran it for the account I wanted and then got the access token and secret for our account. But, I thought, I shouldn’t have to hunt all around to figure out how it works (the documentation is almost all focused on the callback path). Heck, if I know my consumer key and secret and I own the account, I shouldn’t need to know how it works at all. So, having figured out how it works already, I decided I’d write a little command to do it for me and publish it as a gem. Thus was born twitter_atm.

The Tool

As the README states, it’s pretty simple. You invoke twitter_atm get_creds with your consumer key and secret as arguments, then it interactively gives you directions on how to finish out the process and spits out the access token and secret at the end. I do want to note, about the name, it’s not about cash. It’s about inputting a PIN and getting something in return. It’s not very exciting to use, so I won’t talk about it much. I’d rather move on to…

An Old God of Asgard

This was the first time I’d written a program with a command line interface, so I asked around a little about gems that were good at that and Jonathan Otto (of Dealzon) pointed me at thor. In short, thor seems awesome. It’s got a nice DSL for describing the various subcommands of your application and it looks deep enough to handle something more complex than my purposes with twitter_atm.

As a brief example, consider git pull --rebase origin master. If you were writing something that would support this syntax in thor, it would look something like this (I made up the git commands inside off the top of my head, so it’s a bit naive):

1
2
3
4
5
6
7
8
9
10
11
12
13

class Git < Thor
  desc "git pull", "Fetches and merges stuff into the current branch."
  method_options :rebase => :boolean
  def pull(remote, branch)
    `git fetch #{remote}`
 
    if options[:rebase]
      `git rebase #{remote}/#{branch}`
    else
      `git merge #{remote}/#{branch}`
    end
  end
end

You can also declare different types of options, default values, etc. Have a look at the fairly extensive readme and look at how I used it in twitter_atm if that helps. I quite recommend the gem and already have another project I’d like to use it on.

bundle gem twitter_atm

There’s this little project–I don’t know if you’ve heard of it–called bundler. It was started by a couple of up-and-coming young programmers who really might go somewhere some day. Bundler is great for managing gems in a big project and it does this really impressive dependency resolution thing. But there’s a lesser known command that I’ve fallen in love with: bundle gem <gem_name>. It just makes a skeleton for a gem project for you. Unlike Jeweler, it only gives you the bare minimum and really just gets out of your way. You manage your own version number and write your own gemspec (gasp!).

It has three handy rake tasks with obvious functions: rake build, rake install and rake release. Each of those for the most part just issue various gem commands. I basically like it because it builds you a little foundation and then doesn’t really manage anything else for you. One thing that’s important to note: The current version of bundler doesn’t add Gemfile.lock to the .gitignore that it generates (but future versions will), and it is important that you do so. Yehuda has a blog post explaining why.

So, based on this experience, here’s what I took away: Thor is good to use for making a CLI, bundle gem is good to use for making a gem and sometimes you can make something small and cool for yourself in one sitting which gives you a good feeling and is a well invested 5 hours.

Over the past, roughly, 8 months I have gotten into playing a game called Dominion. It’s a card game that is often mistaken for Magic: The Gathering, but in many ways it plays more like some of the more complex board games out there (of which Settlers of Catan may be the most widely known, but not the best example for comparison). In it, there is a pool of common cards which each player may purchase on their turn via a currency mechanic. Cards purchased go into your deck which is drawn from  to make hands and periodically shuffled. It has a bit of the deck-building meta-game of Magic, but in a more primary role and without the annoying, money-sink aspect that collectible card games have. Everyone at the table is drawing from the same central pool of cards, so you can’t spend your way into a better deck between games.

Another aspect that I really like is that the pool of cards for purchase is not the same for each game. You (generally) randomly select 10 types from the box. The initial release had something like 28 types in it. There have been expansions released to add variety, but remember, it’s not a CCG, so buying expansions doesn’t give an advantage to any player over others except, I suppose, that they’ll have greater familiarity with what the cards do. I don’t want to get too into the rules and how the games works. Rio Grande has the rules available as a PDF, so you can go read them in full at the link above. What I really want to talk about is a little hacking exercise that I got into because of the game. Henceforth, I’ll assume you’ve at least read the base rules.

The Discussion

I’ve been playing at lunch with some of the guys at work and I got into a discussion with @hoonpark after one such game. The strategy we were discussing was using Chapel and Treasure Map together. For quick reference, Chapel lets you trash up to 4 (other) cards from your hand and Treasure Map lets you, if you have two in your hand, trash both and then put 4 Golds on top of your deck. The idea was to use the Chapel to reduce your deck size such that the likelihood of getting both your Treasure Maps at the same time went way up and then for most of your deck to just be Golds (with which you would buy Provinces). We disagreed on the exact particulars of how it should be played most optimally and I said, “I bet I could code up a simulator that would play this strategy a ton and give us real statistics.” I think the original debate might have been over whether you try to make two pairs of Treasure Maps work before starting to buy Provinces. At least, that’s what I thought would be best, at first. So I got to work the other evening and coded up the following in two or three sittings. Probably a total of an hour and a half or two.

The Simulation

I have the code up on github, or you can look at this gist. It’s messy as hell and you can tell I sort of just wrote it as I thought of it. I did one refactor, which ended up creating the Player class. That part is probably fairly reusable. The other file could probably be refactored and some bits reused. I want to draw your attention to the commented out lines. I made it so that you can uncomment all the puts statements and run it once to see how just one games goes (which might help you learn to replicate the strategy) or you can run it a bunch and just see a summary. I also ran it several times stopping after buying various numbers of Provinces (3 to 6 ended up being interesting).

As I mentioned above, the original idea was to make Treasure Maps work twice before acquiring Provinces. That ended up taking something like 17 turns on average to get 4 Provinces. When I showed it to Hoon, that didn’t match up with his anecdotal experience, so we looked at the difference between what he’d done (much faster) and what I was seeing. After making it so that the bot would only ever do one pair of Treasure Maps, the turn numbers dropped significantly. Another thing that was different was that Hoon would occasionally buy Silver (if he had less than 5 coins) or, say he drew 2 Golds, 2 Coppers and his Chapel, he would not Chapel the Copper and buy a Province. I think we’ve determined that doing those intuitive things are actually slower than taking the turn to do nothing in the first case or Chapeling the Copper and just buying a Gold.

The Data

The data out of this simulation looks like this (I ran 100,000 games):

• To acquire 3 Provinces, it takes a minimum of 11 turns, max of 13 and average of 13.93
• To acquire 4 Provinces, min: 12, max: 14, avg: 13.93
• To acquire 5 Provinces, min: 15, max: 17, avg: 16.93
• To acquire 6 Provinces, min: 16, max: 18, avg: 17.93

Notice the gap between 4 and 5. It’s spending those two turns buying Gold , probably. I might, for my own curiosity, run it where it buys Duchies instead, but that could have a slowing effect on the following two turns. Speaking of slowing effects, one thing that I found particularly interesting is that if you don’t ever Chapel Estates away, it dramatically increases turn counts. I set a limit of 100 turns and didn’t count those just as a practicality issue. When running this the published way, I never hit it. When running it without Chapeling Estates, you hit it so often that the simulation took long enough that I got worried and killed it. That’s just 3 krufty cards making a huge difference and really underscores why lean deck strategies are often so powerful.

The Limitations

The biggest limitation of this simulation is that it’s playing in a vacuum. There are no opponents and, more pertinently, no one playing Attack cards (or Masquerade, etc.). If an opponent were to bring Theif to the table, that could be potentially murderous to this strategy. I’m not really sure how the simulation would account for that, anyway. I guess you could figure out tons of strategies, then generate sets of Kingdom Cards and see how they fared against each other in various permutations. That sounds like a) a ton of work for me (or another human), b) a ton of work for some computer somewhere and c) like it might take some of the intuitiveness and gut-checking that I find enjoyable in Dominion. So I don’t think I’ll be chasing that down. I might, however, code up a few other strategies to see how they fare. It would be pretty simple to do a “Just Buy Money” to establish a baseline and a Chapel/Remodel; maybe Village/Smithy, since that’s popular and simple.

This is not intended to be a how-to. I sort of talked a bit about that before. I’m writing this post because, as I breathlessly blogged before (alliteration!), I released my first gem. I then immediately turned around to start using it. And it was terrible. Yay for version 0.1! So I’m going to try something else.

The thing that sucked so bad was the API, basically. I didn’t really know how I wanted to use it or how best to fit it into a Rails app. I made a reasonable guess and got to work. It wasn’t a terrible first try, but it was a terrible API. However, I’m not sure what better looks like yet. And I think that I sort of got ahead of myself; I put the cart before the horse.

It’s a little like making the transition from drawing on paper to creating art with the GIMP. When you’re on paper, you draw the stuff that’s in front first and you only draw as much of the stuff that’s behind other stuff as can be seen. So you learn to think a certain way about how you build up your picture. In a program that has layers, you can draw in any old order and draw something entirely even if it’s obscured by something else in the long run.

I was thinking that the obvious path would be to develop my little gem of functionality and then use it in the larger Hey Go Vote application. Now I’m starting to think that’s backwards. I’m going to just work on Hey Go Vote and trust that doing so will give me insight into what parts of the announcement machinery can be made portable. Then I’ll extract those bits into a gem and refactor Hey Go Vote to use the new gem. I’m sure I’ll let you know how that goes.

I just released my first ruby gem, twitter_alert. It’s intended to be a component of the side project I mentioned forever ago, HeyGoVote. It grabs all the followers for a Twitter account and DMs them a message. The messages have dates on them because their intended to be schedule ahead of time. I’ll crib from the readme near the end, but if you want, you can go read the whole thing for yourself. First, I’m going to talk a bit about my experience writing my first gem.

Jeweler

I used the jeweler gem to create a gem template for this guy. It’s very simple and was a huge boon considering this was my first time. It scaffolds out the directory structure for you, sets up some handy rake tasks and generally gives you guidance on how to structure your gem. The readme for jeweler is very helpful. I won’t bother to restate what it says, but seriously, new to gems or not, you should have a look at jeweler if you haven’t already. One of the nicest things is that it’ll generate your gemspec file for you and also handle version bumping in a semantic versioning compatible way. It also integrates with git and GitHub in some interesting ways.

Gemcutter

Jeweler will also handle publishing your gem to “gemcutter” for you, which is nice. I say that in quotes because, of course, gemcutter.org is no longer a thing and their stuff all got officially adopted by rubygems.org, so it actually publishes to there. The jeweler documentation, though, all acts as if gemcutter were still a separate thing. This could be potentially confusing, I guess, but it ends up working right, so it’s fine. It does use the gemcutter gem to manage the publishing, so you’ll have to have that installed, and make sure you have a rubygems.org account and api key set up. The api key goes in ~/.gem/credentials as you’ll learn on your rubgems profile.

twitter_alert

I’ll crib from my readme example to show the most basic setup:

1
2
3
4
5
6
7
8
9
10
11

require 'twitter_alert'
 
account = TwitterAlert::Account.new :user_name => 'benhamill', :password => 'thisisnotmyrealpassword'
 
class Alert
  include TiwtterAlert::Alert
end
 
alert = Alert.new 'Very important message.', DateTime.now
 
account.announce alert

In the wild, I don’t imagine that your Alert class will be so simple. For instance, when I plug this into HeyGoVote, it’ll be included in an ActiveRecord model so I can run a cron job that pulls out tweets that should go out today (based on the date) and sends them all.

I haven’t plugged this into code yet, and note the version number 0.1. The tests pass, but they may not be comprehensive and I might have botched something up in my publishing, but it looks like everything’s working to me. My next step is to start building up HeyGoVote and using twitter_alert in it, which might reveal some needed features. In the meantime, I welcome feedback. Leave a comment here, or fork it and issue me a pull request, if you have an idea.

At the last Austin on Rails meeting (Nov 17), I gave a talked entitled Practical Git Quickstart (Prezi link). The slides don’t have a lot of content and mostly underscored what I hoped to talk about. I blew through them in about ten minutes or less. The short of it is that I feel like a lot of git tutorials and introductions start off with the high-level stuff and that, especially for people new to git, that that’s confusing. My goal was to give git newbies the most basic commands they’d need to be able to use git on a daily basis so that they could build their own abstractions before diving into the more heady stuff. I was aiming for an 80% solution to that, anyway.

After I finished the slides, I fired up a command line and an editor and just worked through some stuff. This post should sum up what I talked about, more or less. I started out covering the same stuff I covered in my previous git tutorial post, so maybe go check that out first. It should get you through setting up a new repository, adding files to the staging area, making a commit, checking your status and committing to a remote repository.

So let’s pick up there, with remote repositories. The way you get code up to your repo is with git push origin master. Once it’s up there, other people can get at it. If you recall, you told git where your remote repo was going to be with git remote add origin git@github.com:<username>/<project>.git. Someone who wants their own local copy of your repo does so with the clone command like so: git clone git@github.com:<username>/<project>.git. That will create a directory wherever the command is issued, named <project> and pull down the current state of the remote repo. Then, that person will be able to push their own changes, etc. This is all, of course, assuming they’ve got permission to do so.

So this new second person makes some changes and pushes them on up. How do you get them? Well, sensibly, the opposite of push is pull, so you issue git pull origin master. This is actually a two step process that’s just for convenience. I don’t want to get into the plumbing too much, but it basically grabs the state of the remote repo (git fetch) and then attempts to merge (git merge) it with your local stuff. So that’s the most basic case of working with someone else on a project, or working alone on one using different machines, if you like. I use that case all the time.

So what about conflicts? If you both make a change to the same file and they push it first, you’ll not be allowed to push because git can’t handle the merge on it’s own. Similarly, if you try to pull, it will do the fetch part, but be unable to merge and will tell you so. You can use git diff to see what the changed were and do the merge yourself. You can also use git difftool which is awesome, but takes some setup, so you should look into it later on (I skipped it in my presentation).

Once you handle the conflicts, you’ll add the conflicting files to the staging area and make a commit. With all merges, I should note, git makes a commit just for the merge, so when you have conflicts, it’ll have staged the things it can merge on its own and left the conflicts unstaged. As you fix them, you stage them and then you commit the merge commit. Git doesn’t know if you really fixed the conflicts, so you can git add whatever version of the file you want, even a broken, not-conflict-resolved one. Just be aware.

That was more or less the end of my ordered presentation. There were some questions afterward and I’m going to attempt to sum up the discussion that followed, here:

First off, I wanted to mention how you ignore files in git. Unlike subversion, there is no git ignore. If you want git to ignore a file, you have to add it to a .gitignore file. This file is a list of patterns that git will ignore for the directory it’s in and all directories below it. So you might have one for a python project like this:

tmp/*
*.pyc

This will ignore all compiled python code (*.pyc) and everything in your tmp/ directory. I was baffled by this when I first came to git, but it’s not really that hard. Note that you generally commit your .gitignore so that others can share it. If there’s something you want to ignore on a per-machine basis, rather than a per-project basis, then you need to turn to my next topic.

Which is global git preferences. On Linux and Mac, git will look for a file in your root directory called .gitconfig and take global behaviors from it (it’s tricky on Windows, and I haven’t figured it out to my own satisfaction, sorry. If someone asks about it, I’ll try to sum up what I know in the comments). In my other git post, I had gone through setting up a repo on GitHub and said to follow the directions there. Two of those steps were these:

git config --global user.name "<your name>"
git config --global user.email <your_email>

Those created entries in your ~/.gitconfig telling git your name and email address. You can also declare a global ignore file there. I like to call mine .gitignore. This is shockingly original, I know. On the machine I’m typing on right now, my ~/.gitconfig looks like this:

[user]
email = blah@blah.blah
name = Ben Hamill
[core]
excludesfile = /home/ben/.gitignore

I bet you can guess it, but just in case, you can either put your excludesfile in manually or do git config --global core.excludesfile /whatever/file/path/you/want. For reference, my ~/.gitignore looks like this:

*.kpf
*.swp

A .kpf file is a project file created by Komodo Edit, which I used to use for all my code editing needs, but not since I switched to vim, which is what creates *.swp files.

Finally, someone had asked about git stash. It’s what I’d consider a more advanced command, but a lot of git fanboys sell it hard because it’s cool and svn doesn’t have it. However, as cool as it is, I think it can get you into a lot of trouble. Basically, you can be working on something and issue git stash and git will store whatever changes you’re in the middle of and hide them away, putting your repo back in the state it was right after the last commit. You can then work on something more pressing, make commits, merges, new branches, whatever and when you’re done, issue git stash pop and it applies your changes back (if it can).

The really hairy bit is that you can name stashes and so have more than one stash going at once. While a super organized developer might find this really useful, I find that it’s easy to get stuff lost in there. You don’t want to have tons and tons of stuff stashed and not remember, anymore, what changes were in which stash, etc. I advise, as a basic rule of thumb, that if you’ve already got one thing stashed and find yourself wanting to stash something else, then you should be looking at branching, not stashing.

I think that about covers it. I think someone recorded audio of my talk or maybe video. If it ends up posted somewhere, I’ll come edit this post with a link to it. If you were at my talk and notice something I talked about then that I haven’t covered here, let me know and I’ll try to amend. Or, if you weren’t there and feel there’s a topic you have questions about, drop it in the comments and I’ll do what I can.

National elections, especially the Presidential elections, get a lot of attention in the US. People talk for months about who might campaign before people even announce their candidacy. There are news stories all over the place covering them. On the other hand, more local elections (for state reps or city councils, etc.) get a lot less coverage (because it’s not CNN’s job, for instance). Right after this most recent Presidential election, I realized that I hadn’t voted at all since the previous Presidential election. In four years, I hadn’t cast a ballot, and I thought I should probably become somewhat more involved in local politics. Or, if not involved, at least aware.

One of the buildings adjacent to the one where I work is a polling location. In Texas, that means I can vote there during early voting. A few months ago, I was cutting through that lobby and saw voting booths set up. “Oh!” I thought to myself, “I wonder what we’re voting on today.” I could have voted right then, but I had no idea what was on the ballot, what the various opinions and angles were, etc. It would have been totally uninformed and random, so I refrained, but I started thinking about how I could be forewarned about elections so I could do my own research.

I could start watching the evening news or following local (or state-level) political blogs or take the local paper. But that’s a lot of overhead which I’ve already decided I don’t want to deal with… and just to get one piece of data. So I thought I’d solve my own problem and the way I’d solve it (and solve it for people other than me, who think in a similar way on this issue) was with Twitter.

The Pitch

My initial concept was that I’d set up an app that would store election dates and just tweet them. I quickly realized that it’s a little more complicated than that. If I just tweet on election day, I’ve just recreated the oh-what-are-we-voting-on-today problem. So I need to give some warning ahead of time. @JonLoyens pointed out that a tweet can be easily missed, so I should use direct messages. The beauty, here, is that I can build a reminder service and not have to manage who wants reminders: It’s all just based on who’s following the twitter account.

So the idea is that you’ll follow @heygovote and it will direct message all its followers to warn that an election is coming up. Simple enough and if you want to opt out, you unfollow. Easy.

Three Rules

I want to keep these three things foremost in my mind while I’m working on this thing:

• No Bias – I don’t want to help people decide how to vote, or influence their vote in any way. This is just about prodding people enough in advance that they can do their own research.
• No Data – I don’t want to know who the users are and I don’t want them to have to trust me that I’m not selling information about them to some organization (related to the above, as well). So I don’t want to have to know anything about the user other than their Twitter user name and I don’t even plan on storing that, just asking Twitter who’s following @heygovote.
• No Bother – I don’t want to hassle people. I want to remind people, not badger them. I also don’t want to have to mess with the thing myself to keep it running; it should be fire-and-forget.

Trouble Scoping

It pretty quickly became evident that I needed to decide who my target was. I’d intended to target “Austin”, but that doesn’t really scale gracefully to the county, state and national levels. After talking to my brother, who works on campaigns and the like, I’ve decided I’m going to target Travis County. That catches most of Austin (more to the point, it catches where I live, since this is solving my problem) and also scales up nicely.

For voting purposes, Texas breaks counties up into voting precincts. All the election dates for all the precincts in a given county are the same, so one tweet (or, rather, direct message) will apply to everyone in Travis County. If, beyond comprehension, this becomes wildly popular and other places want HeyGoVote to cover them, then I’ll deal with that as it occurs. My guess is that how elections are handled will be different enough from state to state that it would mean rebuilding the date-getting machinery for each, uh, constituency, as it were.

Where to Start

I haven’t started coding on anything yet; all work to date has been design thinking and research on how I can get a hold of the information I need. I’ve sent some emails back and forth with the Travis County Tax Office (which decides election dates, oddly enough), who’ve been helpful. They don’t seem to have a handy RSS feed of election dates that I can poll, so I’m still working out that side of things.

I will probably start on the reminder side of the application. If I design the DB schema intelligently, it can be very loosely coupled with the data gathering bit. Depending on how it goes, it also seems like the kind of thing that might make a useful Rails plug-in, too. So I might release that on it’s own.

That being said, I expect to use Rails as the tool set. That might seem like overkill since nothing I’ve described has needed a web interface to it, but I have the idea that, after I get the reminder working, it might be nice to build a tool or two that would help people figure out where their polling location is (for folks who skip early voting), what’s on the ballot for their precinct and things like that. If I can’t find existing, non-partisan tools to link to for this, I might have to build my own.

Expect to hear more about this as I work on it. If you have any suggestions or questions, leave a comment.