If you’ve never heard of pingbacks before, you’re out. Go home.

Ok, pingbacks are this mysterical feature when you write on your blog A and refer to some article on blog B. After you publish your article on blog A, something happens behind the curtain. Suddenly there’s a new comment on the blog B article you cited in your text, and this comment links back to your article on your blog A. That’s called a pingback.

Whereas sending a pingback is just a modest effort by fireing some small XML-RPC request, receiving is quite a bunch of work. A pingback’able site needs to

• provide an XML-RPC capable server to receive pings
• check the refering site’s article for the link to us
• excerpt a piece of content from this refering article on blog A
• store the extracted content with the link on the pinged page, maybe as a comment

Fortunately, there’s already a Rails plugin to handle this tedious task, namely pingback_engine which I wrote as a christmas gift for my friends on the net.

Receiving Pingbacks with pingback_engine

To make our Rails app pingback’able we need to install the engine, setup the server url propagation and then hook in a method for processing incoming pings. That is awesomely easy.

Installation

Inside the rails app directory install the engine, and a needed gem.

script/plugin install git://github.com/apotonick/pingback_engine.git
gem install hpricot

Your Rails app is now capable of receiving pingbacks via XML-RPC.

Propagating the server for auto-discovery

However, if a blog links to you, this blog will usually scan your page to discover the XML-RPC pingback server. What a pingback’able page should do to propagate this url is described in the pingback specification.

It roughly says, to define a pingback-enabled page

• either return a X-Pingback HTTP header
• or provide a special link element in the page HTML header
• or do both!

In our example, we’re on the safe side by providing both. I instruct my blog controller to send an X-Pingback header by calling set_xpingback_header in the action that shows my articles.

# file: app/controllers/blog_controller.rb
 
class BlogController
    include PingbackHelper
    helper :pingback
 
    def article
      set_xpingback_header
      # ...

This will send the respective header with the correct url as soon as some blog tries to auto-discover the address for your XML-RPC pingback server.

Additionally, we provide a special <link ..> element in our application layout so the XML-RPC address is visible everywhere in the app.

# file: app/views/layouts/application.html.erb
 
      ...
      <%= pingback_link_tag %>

Now other blogs will find your pingback server if some article links to your site.

Processing an incoming pingback
The only thing we have to implement is the pingback processing method. It’s currently put at the bottom of the rails environment file. Of course I could just delegate to another class method in some model, but for demonstration purpose it’s all in one file.

18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

# file: config/environment.rb.
 
# ...
Pingback.save_callback do |ping|
    comment = ArticleComment.new
    comment.author     = ping.title
    comment.author_url = ping.source_uri
    comment.text       = ping.content
    comment.created_at = ping.time
 
    referenced_article = Article.find_by_url(ping.target_uri)
 
    if referenced_article
      comment.article_id = referenced_article.id
      comment.save
 
      ping.reply_ok # report success.
    else
      # report error:
      ping.reply_target_uri_does_not_accept_posts
    end
  end

Easy. Into the block to Pingback.save_callback we get a ping instance, which is enough to process, check and store the incoming pingback.
I just

• create an ArticleComment instance, which is an ActiveRecord-derived class and represents comments in my blog (line 22)
• assign -or map- values from ping to the comment
• check the ping if it really points to an article in my blog
• decide the incoming ping is invalid and discard it (line 37)
• or save the comment in my blog and report success (line 34)

Anyway, all we have to do now is to login to some blog (recent Wordpress blogs work great) and publish an article that links to a pingback’able page on our Rails site. The blog will send us all the information we need to receive the ping, and the pingback_engine will almost do the rest!

Testing manually
For debugging or testing purposes you can also use a test script shipped with the plugin. All you need is your set up rails site and a HTML page accessable on some webserver. The HTML page must link to a pingback-enabled page on your rails site.

By firing

pingback_engine $> script/send_pingback.rb http://site.com/page_linking_to_us.html http://my.rails.site.com/article-31

you can issue an XML-RPC pingback on the local server and debug things.

However, it should all work as it is shipped, so have fun when making your Rails site pingback’able!

Branching

If you’re planning to

• change huge parts of your code at once
• introduce a complex new feature or another API
• switch easily between different - simultaneously running - development processes of your project (actually, that’s called a branch)

you’re better off creating a new branch. As soon as you switch to this branch, the former version won’t get touched anymore. You can easily merge back the changes from the new branch to your master version.

First, list the local branches

git branch

Creating a branch
You start by creating a new local branch

git branch dynamic

we call the new branch dynamic.

Then switch to your new branch. The code will be the exact state when you left the former branch.

git checkout dynamic

You can now apply changes, commit and push to your new branch.

Don’t forget to push the new branch to your remote repository

git push origin dynamic

Merge the branch back
After you think your changes should go back to the master branch, merge ‘em, where the newer will supersede all of master

git checkout master
git pull . dynamic
git push

{is git pull . dynamic + git push =?= git merge dynamic}

Tagging

I often explain a tag in git as a bookmark which lets you return to some specific version of your code. As you can have an unlimited amount of tags, you can have as many bookmarks as you need.
So when you want to take a snapshot of your code saying “if I had releases, and would package my code, this version would be packaged as 2.2.1.tar.gz” why not simply tag it as 2.2.1?

To list the bookmarks you already made, enter

git tag -l

Creating a tag
Right after you found some nifty name for your tag - let’s say we call it 2.3 - create an annotated (not signed) tag with

git tag -a 2.3

Until here the tag will reside in your local repository only and will be pushed to your remote repos instantly if you command

git push --tags

You can switch back to any version you tagged using

git checkout 2.3

which is really helpful for both developers and users since you can distribute multiple versions in one repository.

Deleting a tag
If you simply want to delete a local tag, do

git tag -d v3.3.4

However, if you need to remove that tag from your remote github repository, you simply push nothing to the tag name.

git push origin :refs/tags/v3.3.4