Mate-driven development

I Did It My Way - Learning Sinatra by example

2010-01-13T00:00:00-05:00

I Did It My Way is a new blog dedicated entirely to the Sinatra framework. It was created by Darren Jones as part of his Sinatra Cookbok project.

Darren’s New Year’s resolution for 2010 is to complete a different Sinatra project every 2 months, so hopefully by the end of this year we will have 6 fully functional Sinatra apps with complete step-by-step guides of how to build them. All applications will be deployed to Heroku and the code will be publicly available on github.

The first project was just published, along with an introduction to Sinatra and a brief tutorial for installing it.

Stay tuned for more!

Continuous notification with Integrity

2009-09-21T00:00:00-04:00

Integrity is a lightweight Continuous Integration server written in Ruby. As any other continuous integration server, it can be configured so that as soon as you push your commits, it builds your project, runs your tests, and makes sure everything is still working fine.

Integrity comes with a simple but powerful notification system that reports the build status to all team members in (optionally) many different ways. Currently there are notifiers available for Email, Jabber, Campfire, IRC, Twitter, Basecamp and Yammer, and they are all easy to set up.

Setting up a notifier

For example, if you want Integrity to send you an email after each build, you can set up the email notifier in 3 simple steps:

1. Install the notifier gem

sudo gem install integrity-email

2. Require the notifier in your config.ru file

require "rubygems"
require "integrity"

# You need to add the following line:
require "integrity/notifier/email"

3. Restart Integrity

That’s it! Now you can configure the email notifier options for each project on your Integrity installation. The process is exactly the same for all the other notifiers.

Creating your own notifiers

As you can see, setting up a notifier is easy. But where Integrity’s notification system really shines is when you start writing your own notifiers.

Creating a new notifier is really simple. There are just a couple of rules to consider:

All notifiers are derived from Integrity::Notifier::Base
At a minimum, a notifier must implement two methods: to_haml and deliver!. The first one must return some markup in haml format that will be rendered on the projects page, and it is useful if your notifier requires some configuration (as most notifiers do). The deliver! method is where the real action takes place, as this is the method that gets called after Integrity builds a project.
Although you can have a notifier working by implementing just these two methods, I would suggest that you also implement the to_s method in your notifier so that its messages are easily identifiable on Integrity’s log file.

Following these rules, we can create a simple Integrity notifier with just a few lines of code:

require 'integrity'

module Integrity
  class Notifier
    class Dummy < Notifier::Base
      def self.to_haml
      end

      def deliver!
      end

      def to_s
        'Dummy'
      end
    end

    register Dummy # Don't forget to register your notifier!
  end
end

Of course, a notifier like this one does not do anything interesting. All it does is to register itself with the Integrity server and write a message on the log file each time it gets called.

A real-life example: the Tumblr notifier

Let’s complicate things a bit more by creating a notifier that will post a message to a tumblelog informing the result of each new build.

One of the first things we need to decide when we create a new notifier is the info that we want to include in the notifications. All Integrity notifiers get access to the following info by default:

Method	Description
short_message	A readable status message. E.g. “Built #{short_identifier} successfully”
full_message	A long message containing all the info available for this commit (commit identifier, status, timestamp, author, output, etc.)
commit_url	Integrity url corresponding to this commit
stripped_commit_output	Build output

In most cases, that is all you will need. But if you have particular needs and/or prefer to have more control over the info included on your notifications, you could also access the commit object directly:

Method	Description
commit.identifier	Unique identifier for this commit
commit.short_identifier	First 7 digits of the unique identifier
commit.message	Commit message as entered by the author
commit.project.name	Project’s name
commit.author.name	Author’s name
commit.committed_at	Timestamp of this commit
commit.status	Build status. Could be :pending, :success, or :failed
commit.successful?	True if commit.status == :success, false otherwise
commit.pending?	True if commit.status == :pending, false otherwise
commit.failed?	True if commit.status == :failed, false otherwise
commit.human_readable_status	A readable status message. E.g. “Built #{short_identifier} successfully”
commit.output	Build output. Use stripped_commit_output instead

For this notifier I will be using the short_message as the post’s title, and the full_message as the post’s body. Let’s see how the code looks like:

# tumblr.rb

require 'integrity'
require File.dirname(__FILE__) + '/tumblr_client.rb'

module Integrity
  class Notifier
    class Tumblr < Notifier::Base
      attr_reader :config

      def self.to_haml
        File.read(File.dirname(__FILE__) + "/config.haml")
      end

      def deliver!
        TumblrClient.post(config['email'], config['password'], short_message, full_message)
      end

      def to_s
        'Tumblr'
      end
    end

    register Tumblr
  end
end

I will also need to provide a configuration form that let us configure both the Tumblr account’s email address and password:

# config.haml

%p.normal
  %label{ :for => "tumblr_notifier_email" } Email
  %input.text#tumblr_notifier_email{ :name => "notifiers[Tumblr][email]",         |
                                     :value => config['email'], :type => 'text' } |

%p.normal
  %label{ :for => "tumblr_notifier_password" } Password
  %input.text#tumblr_notifier_password{ :name => "notifiers[Tumblr][password]",         |
                                        :value => config['password'], :type => 'text' } |

I have already created a gem with this code and published it on GitHub. Feel free to install it and play around with it if you want. Just remember the 3 steps:

1. Install the gem

sudo gem install integrity-tumblr

2. Require the notifier in your config.ru file

require "integrity/notifier/tumblr"

3. Restart Integrity and enable notifications via Tumblr for the projects you want

Recursive notification

Here is the integrity-tumblr notifier notifying me via Tumblr that Integrity has successfully built the integrity-tumblr project itself. Cool!

Resources:

integrity-dummy notifier source at GitHub.
integrity-tumblr notifier source at GitHub.

Using Git to maintain your blog

2009-04-28T00:00:00-04:00

On a previous post I wrote about installing Jekyll and setting up a typical Jekyll-based blog.

Having my blog generated with a single command was nice, but I still needed something else. What I was looking for was something that worked like GitHub pages but on a shared host. In other words, I wanted to be able of writing a new post in my text editor, and then git commit and git push to the server, to see how my blog gets updated without having to do anything else.

After looking at some alternatives and doing some tests, I ended up implementing a simple solution that involves three Git repositories and some hooks to keep everything in-sync:

A local repository containing the blog’s source files
A remote repository replicating the local repository. Whenever something in the blog changes, I run Jekyll on this repository’s working tree to generate my site. I will call this the live repository in the rest of this post.
A remote bare repository that acts as an interface between the local and live repositories. I guess I could live without this one, but I have read too many stories about issues caused by pushing to a git repository with a working tree attached to it, at least enough to discard the idea of pushing from local to live directly. I call this one the base repository.

On this post I will show you how you can implement this solution in your own host.

The following steps assume that you already have a vps or shared host account with ssh access enabled and that both git & jekyll are already installed on your server:

Gitify your blog’s source folder
Set up the remote Git repositories
Hook everything up
Publish your blog

Gitify your blog’s source folder

The first step is to create a new local Git repository that contains your blog’s source files. Assuming you already have a Jekyll-compatible folder structure in place, all you need to do is this:

cd ~/my_jekyll_blog_folder
git init
git add .
git commit -m "Initial blog setup"

Replace my_jekyll_blog_folder with your own folder name, of course.

If you do not have a Jekyll-compatible folder tree yet, take a look at Getting started with Jekyll for more details.

Setting up the remote Git repositories

Now that the local repository is ready, the next step is to create and configure the two remote Git repositories on your shared/vps host. First, let’s create the base repository by opening a ssh session on your host and executing the following:

mkdir -p ~/git/base.git
cd ~/git/base.git
git --bare init

The base repository will serve as an interface between local and live repositories, so now you need to add base as a remote repository to the local repository. To do this, go to your local pc (leave the ssh session open, as we are going to get back there soon) and execute the following:

git remote add server ssh://you@yourdomain.com/~/git/base.git

Also, edit your .git/config file in the local repository and add the following:

[branch "master"]
  remote = server
  merge = refs/heads/master

Creating the live repository is even easier than base, as you can clone the bare repository created before. Notice that git < 1.6.2 will not allow you to clone an empty repository, and therefore you must push something to base first. From your local repository:

git push server master

Now we can switch to the ssh session and create the live repository by cloning base as usual:

cd ~/git
git clone base.git live

Hooking everything up

Ok, we are almost done with this. Let’s add some git hooks to automate the process of generating the site each time we push something to the base repository. To do this, cd to the ~/git/base.git/hooks directory on your server and edit the post-update file with the following contents:

#!/bin/sh

echo
echo "*** Updating live repository ***"
echo

cd $HOME/git/live || exit
unset GIT_DIR
git pull origin master

echo
echo "*** Generating site with Jekyll ***"
echo

$HOME/gems/bin/jekyll

exec git-update-server-info

This script will be executed every time the base repository gets updated. It cd’s to the live repository, pulls the changes from base and finally run Jekyll to re-generate the whole site.

Notice that you need to replace $HOME/gems/bin/jekyll by the appropriate command to execute Jekyll on your own hosted account.

That would be all you need for having a similar workflow than the one used by GitHub pages. But just to be sure that both remote repositories are in-sync all the time, I added the following script to the live repository to push any commited changes back up to base after every commit in live. Put this content into the ~/git/live/.git/hooks/post-commit file:

#!/bin/sh

echo
echo "*** Pushing changes to base repository ***"
echo

git push origin master

In practice I try to avoid editing files directly on the live repository, but this script makes sure that both remote repositories still get synchronized in case I ever need to do that.

Remember to make those scripts executable:

chmod +x ~/git/base.git/hooks/post-update
chmod +x ~/git/live/.git/hooks/post-commit

Otherwise the git hooks will not work.

Publish your Jekyll-powered blog

Now that we are ready, let’s replace your current html directory with the output generated by Jekyll. On the server:

cd ~
mv public_html public_html.old
ln -s ~/git/live/_site public_html

Remember to replace public_html above with your actual html directory (html, /var/www, etc.).

Conclusion

That is it. You can now start writing your posts on your local _posts directory. Whenever you are ready, all you need to do in order to update your blog online is executing the following:

git commit -am "New post: Using Git to maintain your blog"
git push

The git hooks will take care of synchronizing the live repository and re-generating your blog with Jekyll.

Happy blogging!

Resources:

The original Git workflow on which I based mine can be found at A web-focused Git workflow by Joe Maller.
Daniel Miessler wrote another post on this topic, using a similar approach: Using Git to maintain your website.
For more details on creating a private Git repository on your shared host account, take a look at John Nunemaker’s Git’n your shared host on article.

Getting started with Jekyll

2009-03-25T00:00:00-04:00

Jekyll is a simple static site generator created by Tom Preston-Werner that is used as the engine behind the well-known GitHub Pages.

I must admit that the first time I heard about this, the idea did not grab my attention at all. But after reading some inspiring blog posts about it, everything started to make sense and I decided to give it a try on my new blog, and so far, I like it.

Installing Jekyll

The easiest way to install Jekyll is via RubyGems:

sudo gem install jekyll

Notice that Jekyll requires directory_watcher, liquid, open4 and maruku. They will be automatically installed by the gem install command.

Creating content

Basically, what Jekyll does is to take several .textile or .markdown files and translates them into html, optionally using layout templates to avoid duplicating the common areas of our blog on each post. So, all we need to do is place our own content files in the correct locations.

A typical Jekyll blog setup would be as follows:

An index.html file on the root directory that will serve as the home page of our blog.
One or more template layouts in the _layouts directory. These layouts can then be referenced from any other file by using the layout attribute in the YAML header. Also notice that layouts can be nested.
One .textile or .markdown file for each post in the _posts directory.
One .textile or .markdown file for each draft in the _drafts directory. Any posts in this directory will be ignored by Jekyll at generation time.
One or more .textile or .markdown files in the _includes directory. Any files located in this directory can be included into another file with the include tag.

For a starting point, you might want to take a look at Tom Preston-Werner’s TPW repository.

Generating the blog

Once that the basic layout and content of our blog was set up, we are ready for telling Jekyll to generate our site:

jekyll

If everything goes well, by now we should have our brand new Jekyll-powered blog generated on the _site directory.

We can also run Jekyll with the --server flag in order to test the generated site:

jekyll --server

This flag tells Jekyll to launch a WEBrick server instance. Now we can point our web browser to http://localhost:4000 and test the generated site locally.

Publishing everything

At this point, we can just ftp the contents of the _site directory to our web site and we’re done.

However, a much better solution would be to create a remote git repository and add some git hooks there that take care of generating the site for us each time we do a simple git push. That is exactly the setup I am using to maintain this blog, and I will be writing about it in a future post.

Conclusion

This solution is definitely not for everyone. But if you are a programmer, and especially if you spend most of your day working with a text editor and a terminal window opened, then you may find the combination of Jekyll, Git, and your editor of choice (vim, in my case, but Emacs, TextMate or any other would work just fine, of course) more appealing than any traditional blog software.

Should be or should_not be...

2009-03-20T00:00:00-04:00

I found this nice piece of Ruby poetry today on the rspec-users mailing list, and I thought it would be nice to pass it along.

should be || should_not be: that is the expectation:
Whether ‘tis nobler in the parser to interpret
The outputs and side effects of outrageous duck typing,
Or to inherit against a sea of matchers
And by declaration extend them? To fail: to raise;
No more; and by a raise to say we throw
The exception and the thousand natural returns
The code is heir to, ’tis a specification
Devoutly to be wished. To fail: to raise;
To raise, perchance to rescue: ay, there’s the rub,
For in that state of exception what tests may fail
When we have injected in this matcher code
Must give us pause: there’s the RSpec
That makes calamity of such long backtraces;
For who would bear the Flogs and Heckles,
The oppressor’s Reek, the proud man’s Cucumber,
The pangs of despised Rcov, the spec_server’s Drb,
The insolence of Autotest and the spurns
That patient merit of the occasional Rakes,
When he himself might his validation make
With a bare assertion?…

— Stephen Eley