Ever used a rubygem, found a bug, and just wanted to quickly bust out the big guns and fix it quickly?

The gem command doesn’t come packed with a way to find the original source repository for a gem. At best, most gems at least come bundled with the complete source, tests and documentation. Some gems don’t. Fair enough, since having access to the complete source via the gem still doesn’t allow you to fix a bug and share it with the world.

For that you access to the repo, a quick way to fork it, and a post-github way to share a gem version from yours truly.

The github gem and gemcutter are the modern day tools of master hackermanship.

Instant forking fun

Let’s say you find a bug in a gem, say rails, and you want to go to town on its source.

You know the gem is called rails but you’ve no idea what the github repo is called. Never fear.

$ sudo gem install drnic-github
$ gh clone --search rails
Select a repository to clone:
1.  rails/rails                         # Ruby on Rails
2.  technoweenie/restful-authentication # Generates common user ...
3.  justinfrench/formtastic             # A Rails form builder plugin ...
?

Press 1 and you’ll get a clone of rails/rails.

Alternately, if you want a fork or you know the exact user/repo already:

$ gh clone rails/rails

Now, fork your own version:

$ cd rails
$ gh fork

You now have your own fork. The origin remote also now points to your fork rather than the rails/rails repository:

$ git remote show origin
* remote origin
  Fetch URL: git@github.com:drnic/rails.git
  Push  URL: git@github.com:drnic/rails.git

So, make your changes, push them. Send a pull request or github issue or lighthouse ticket or what have you.

Want to get to the github project home page for your fork?

$ gh home

Instant gem sharing

Let’s say you patched the rails gem itself but you want to share your changes via your own gem.

In the olden days, github did this for you. Now you use gemcutter, and a little manual effort to do your own renaming.

First, install the gems locally, use them, and make sure all is good.

For rails, you install the edge gems (3.0.pre) with:

$ rake install

You can’t see ‘rake install’ in the rake -T list (hence my patch), but I think the following expression displays all tasks regardless if they have a description or not:

$ rake -P | grep "^r"

Rails is composed of several gems, unlike most projects that are distributed as a single gem. Here we want to share our commit within a new drnic-rails gem, but not touch the others.

Edit the railties/rails.gemspec file from:

Gem::Specification.new do |s|
  s.platform = Gem::Platform::RUBY
  s.name = 'rails'
  s.version = '3.0.pre'
...

and give your personal gem a new name:

Gem::Specification.new do |s|
  s.platform = Gem::Platform::RUBY
  s.name = 'drnic-rails'
  s.version = '3.0.pre'

To build and distribute the new gem:

$ gem build railties/rails.gemspec
$ sudo gem install gemcutter
$ gem push drnic-rails-3.0.pre.gem
  Pushing gem to Gemcutter...
  Successfully registered gem: drnic-rails (3.0.pre)

Follow any first-time gemcutter instructions and SUCCESS! Now I have my own drnic-rails gem.

Summary

To find, clone, and fork any rubygem that is hosted on github:

$ sudo gem install drnic-github
$ gh clone --search rails
$ gh fork

To personalise the gem and share it on gemcutter:

> edit the project.gemspec to have a unique name, e.g. yourname-project
$ gem build project.gemspec
$ sudo gem install gemcutter
$ gem push yourname-project-1.0.0.gem

I think this makes it much easier, faster and more fun to hack other people’s stuff.

Related posts:

1. Migrating project websites to github pages with sake tasks, new websites with jekyll_generator Its almost Christmas time and that means presents. It...
2. newgem 1.0.0 all thanks to Cucumber The New Gem Generator (newgem) was exciting, moderately revolutionary, and...
3. My attempt at sake task management I’ve used sake intermittently in my workflow. It competes...

This article is out of date in some aspects. See comments.

Today I had my first look at rails 3.0.pre and below are the sequence of steps I had to take to create a rails 3.0.pre application, and get it’s generators to work.

Why was I looking at the top-secret, yet open-source Rails 3.0? Their generators are being migrated over to Thor and I wanted to see them in action. I was thinking I might migrate newgem to use Thor too.

Here’s a quick poke around of getting started and interesting things I found. Any hiccups and workarounds are meant as a guide to pre-pre-3.0 users/developers and not as a criticism of rails-core. Rails 3.0 is looking shiny and awesome.

NOTE: Since this is a “how to install and use” rails 3.0 edge, which is still in heavy development, this set of instructions might break. Let’s hope not.

Getting Started

As of today, you cannot install 3.0.pre from rubygems [1]. So, let’s install them from source. Which is handy, you might like to patch something.

$ cd ~/gems
$ git clone git://github.com/rails/rails.git
use_ruby_191 *

[*] If you are on OS X Snow Leopard I think you can ignore this. Otherwise, since you don’t have the 3.0.pre gems installed, you’re about to hit bump #1. Ruby 1.8.6 doesn’t have Symbol#to_proc but it’s required to create a rails app. This means you’ll need to be able to switch to another version of ruby temporarily if you’re on ruby 1.8.6 [2].

cd ~/Sites
ruby ~/gems/rails/railties/bin/rails

Oooh, look at all the new options! Some new ones are:

-F, [--freeze]             # Freeze Rails in vendor/rails from the gems
-O, [--skip-activerecord]  # Skip ActiveRecord files
-T, [--skip-testunit]      # Skip TestUnit files
-J, [--skip-prototype]     # Skip Prototype files

The -D, --with-dispatchers flags have been removed. --freeze isn’t new, but -F is.

So, to create an app, I dutifully used:

ruby ~/gems/rails/railties/bin/rails edgerailsapp -F

BAM! Fail. The -F option to freeze/vendor rails fails without the gems installed. So don’t use it.

ruby ~/gems/rails/railties/bin/rails edgerailsapp
ln -s ~/gems/rails vendor/rails

If you’re on Windows without the symlink command ln, then copy the downloaded rails source into vendor/rails.

Fetch Rails’ dependencies

Rails 3.0 source uses the new bundler project to describe its own dependencies. From Nick Quaranto’s article on bundler, get the latest:

cd ~/gems
git clone git://github.com/wycats/bundler
cd bundler
sudo rake install

Now, back in your app, you need to install some rails dependencies here too. It’s a good chance to see how you’ll bundle gem dependencies in the future.

$ cd ~/Sites/edgerailsapp

Change the Gemfile in your project to the following:

gem "rack",          "1.0.1"
gem "rack-mount",    :git => "git://github.com/rails/rack-mount.git"
gem "rack-test",     "~> 0.5.0"
gem "erubis",        "~> 2.6.0"
gem "arel",          :git => "git://github.com/rails/arel.git"
gem "sqlite3-ruby"
gem "rails", "3.0.pre", :git => "git://github.com/rails/rails.git"

Welcome to the future of gem dependencies for rails apps. Ultimately you won’t need to manually add these lines yourself. When rails is distributed as gems it will automatically install these for you, I assume/hope/guess. But for today, you seem to need them.

Now locally (within your app) install these gems:

$ gem bundle

If you get “can’t convert Pathname into String” then revert to ruby 1.8.X and reinstall bundler into your 1.8 gem cache.

Phew. Ooh, my god. Phew. Only now will script/generate work.

$ script/generate

For me, this outputs:

Please select a generator.
Builtin: app, controller, generator, helper, integration_test, mailer, metal, migration, model, model_subclass, observer, performance_test, plugin, resource, scaffold, scaffold_controller, session_migration, stylesheets.
Others: app_layout:app_layout, check_migration_version:check_migration_version, home_route:home_route.

The “Builtin” generators are the latest and greatest in Thor technology. Rails 3.0 no longer uses its own generator but is built upon Thor.

For example, our old favourite model generator works thusly:

$ script/generate model Post title:string --no-fixture
    invoke  active_record
    create    db/migrate/20091103030824_create_posts.rb
    create    app/models/post.rb
    invoke    test_unit
    create      test/unit/post_test.rb

Interestingly, --no-fixture isn’t mentioned in the usage information for script/generate model. It mentions the --fixture flag, but I had to guess that --no-fixture was also supported.

Hmm, I want to use rspec. So, let’s destroy these files:

$ script/destroy model Post title:string
      invoke  active_record
.../vendor/gems/dirs/rails/railties/lib/rails/generators/active_record.rb:14:in
  `next_migration_number': uninitialized constant ActiveRecord::Base (NameError)

Oh well.

What if I wanted to run rspec and cucumber generators, for example, against an edge rails app?

Rails 2 generators

The “Others” generators are my own local generators from ~/.rails/generators. Amusingly, instead of app_layout it is called app_layout:app_layout. Not surprisingly at all, if I try to run the rails 2 generator it fails:

$ script/generate app_layout:app_layout
[WARNING] Could not load generator at "/Users/drnic/.rails/generators/app_layout/app_layout_generator.rb". Error: uninitialized constant Rails::Generator
Could not find generator app_layout:app_layout.

Poop.

Note, I have rspec, rspec-rails and cucumber gems installed locally but I cannot see their rails generators above. Rails 3 doesn’t look for generators in the same way and old Rails 2 generators don’t work anymore.

That’s the news: every rails 2 generator is broken.

When I start to migrate some of mine I’ll post about it. In the meantime, José Valim has written some introduction thoughts on using Thor as a generator.

You can also probably learn about how to write rails 3.0 generators by looking at the source code for the new generators like rails, model (see main and test_unit), and scaffold/resource.

Finally, José Valim has a sample Rails 3 app with some vendored generators in it.

These are the things I’m researching now.

Summary

This article is long, mostly because rails 3.0.pre hasn’t been released as a set of RubyGems. If it had, then all the dependencies would be installed automatically.

It also introduces gem/plugin writers to the first upgrade issue: your current generators are neither discovered nor work by a rails 3.0 app. We’re all clever cookies, so here’s hoping we can figure out the upgrade path and that it’s simple enough to not be the topic of Dan Brown’s next book.

Footnotes

[1] Two portions of rails 3.0.pre are available as pre-release gems: activesupport (which is now very modularised and only loads up the parts that you require) and activemodel (which is shiny and new and hence completely safe for rails-core to release).

[2] There are two popular ways to have easy, non-intrusive access to alternate versions of ruby: rvm and ruby_switcher.sh.

Related posts:

1. Rails themes can remember things I was getting annoyed at having to remember all the...
2. Install any HTML theme/template into your Rails app Have you ever even bothered to Google for “rails...
3. Closing in on The Dream: “one-click-to-deploy Rails apps” Got a simple app you want to build? Allocate...

By default, Rails’ integration stack only calls into the routes/controllers. So the following fails, ironically with a 404 error:

$ script/console
>> app.get '404.html'
=> 404

It should return 200. If I cache a file into public/ I want to be able to pull it back out during the normal course of integration testing.

In integration testing, this problem manifested when I clicked a link to a cached asset, or an action redirected to a cached asset.

Ryan Tomayko seems to also have wondered about this, and had this conversation with Pratik Naik on twitter the other day that solved the problem for me:

What worked for me was to put the following at the bottom of my config/environments/cucumber.rb file (or your …/test.rb file if you do integration testing in that environment):

config.middleware.use "Rails::Rack::Static"

Now, I can successfully load assets via the get helper, or indirectly via webrat clicking links, etc:

$ script/console cucumber
>> app.get '404.html'
=> 200

So, install_theme now helps each theme folder remember the previously used settings.

gem install install_theme  # version 0.7.0+
install_theme path/to/rails_app path/to/template #content_box \
      --partial "header:#header h2" \
      --partial sidebar:#sidebar"

Now, the next time you apply that same theme to another project you don’t need to mention “#content_box” or use the --partial flags:

install_theme path/to/another_rails_app path/to/template

How?

If you squint your eyes just right, you’ll notice that your original template folder now has an install_theme.yml file. It contains your original settings. You can imagine for yourself how the rest of the “themes can remember things” magic might work.

Templates “For Ruby on Rails”

If you are a template maker, you can now easily make your HTML template “For Ruby on Rails” by including an install_theme.yml file. Think of the children.

Major change

I changed the order of the first two arguments. In future, the path/to/template will be optional. Why? Imagine if each theme you ever used was cached in ~/.install_theme/themes and you could select a theme from a list or by --theme theme_name. That seems neat.

Related posts:

1. First look at rails 3.0.pre This article is out of date in some aspects....
2. Install any HTML theme/template into your Rails app Have you ever even bothered to Google for “rails...
3. Closing in on The Dream: “one-click-to-deploy Rails apps” Got a simple app you want to build? Allocate...

Perhaps I’m a bit delirious but I think it would be fun to paste features/112_users_crud.feature into the console and it would run the scenarios:

$ features/users_crud.feature

instead of having to always do the extra key strokes:

$ cucumber features/users_crud.feature

Solution?

Two steps:

1. At the very top of each feature file add: #!/usr/bin/env cucumber
2. Run chmod +x features/*.feature

Shazam!

Hash bang me up!

To apply this to all your feature files, jump into script/console or irb and run the following code within your project:

Dir["**/*.feature"].each do |feature|
  contents = File.read(feature)
  File.open(feature, "w") do |f|
    f << "#!/usr/bin/env cucumber\n\n"
    f << contents
  end
  `chmod +x "#{feature}"`
end

Related posts:

1. Cucumber: building a better World (object) How to write helper libraries for your Cucumber step definitions...
2. Testing outbound emails with Cucumber My testimonial for Cucumber still stands even in 2009....

Have you ever even bothered to Google for “rails html template”? There are millions of “Wordpress themes” you can download for free or less than $100, a thousand times more static HTML templates, but never any category of template called “Ruby on Rails theme”. 24 millions results for Googling single column html theme.

So we’re only left with HTML templates. Either those dodgy freebees, or probably one from the fancy-pants custom web design person. But how do we install them to our Rails apps?

I don’t know. It sucks. And it takes more time than it should. Here’s my idea – a tool to install any HTML template into your Rails app. To treat any HTML template as if it was a “Ruby on Rails HTML Template”.

So I’ve started to try and make any “HTML Template” into a “Ruby on Rails Template” with the helper app install_theme.

What’s it do?

Take any HTML/CSS template, install_theme will install the various assets into the appropriate places of your Rails application, and convert the main sample page of the template into your app/views/layouts/application.html.erb (or .haml). Easy peasy.

Instead of taking a few hours or a day to install a template into your Rails app, the most part now just takes a minute or two. Into either ERB or Haml. Repeatable if the original HTML/CSS template changes.

Consider a free admin template Refreshed [download].

Installing a theme for fun and profit into a fresh rails app:

$ gem install install_theme
$ rails my_app
$ cd my_app
$ install_theme . path/to/theme/folder ".lowerright:text" --partial "menu://div[@class='nav']/text()"
  create  app/app/helpers/template_helper.rb
  create  app/controllers/original_template_controller.rb
  create  app/helpers/template_helper.rb
  create  app/views/layouts/_menu.html.erb
  create  app/views/layouts/application.html.erb
  create  app/views/original_template/index.html.erb
  create  public/images/footer.png
  ...
  create  public/stylesheets/style.css

Your theme has been installed into your app.

When you launch the app, it will be instantly themed. The section of the original template with DOM path .lowerright will be removed and replaced by your rendered actions.

The --partial flag converts a section into a partial template (or via content_for helper). More on this in a minute.

Note: the example above uses both CSS path and XPath expressions. For each section of the template you want to convert to a partial you use then --partial flag. The argument is “label:xpath” or “label:csspath”. So either --partial "header://div[@id='header']/h2" or --partial "header:#header h2".

Here are the content and partial selections using CSSpath:

$ install_theme . path/to/theme/folder ".lowerright:text" --partial "menu:.nav:text"

Here are the content and partial selections using XPath:

$ install_theme . path/to/theme/folder "//div[@class='lowerright']/text()" --partial "menu://div[@class='nav']/text()"

Overriding the theme partials

Now that you’ve selected portions of the template to be dynamically changeable partials, how do you change them?

1. Use <% content_for :menu do %> ... <% end %> from any view template
2. Create a _menu.html.erb partial in your controller’s views folder, e.g. app/views/posts/_menu.html.erb
3. Modify the _menu.html.erb partial in the app/views/layouts folder. This is the default source.

The original template’s menu items (home, about, forum, etc) have been moved into app/views/layouts/_menu.html.erb. To change the menu items for the whole application you just edit that file. For this template, it will look like:

<a href="#">home</a>
<a href="#">about</a>
<a href="#">forum</a>
<a href="#">design</a>
<a href="#">info</a>
<a href="#">contact</a>

This is the extracted content of the .nav DOM element. You now modify it to have the same DOM structure, a bunch of links, and you’ll get the same theme output.

Let’s change the menu across the entire application. Edit app/views/layouts/_menu.html.erb:

<%= link_to "home", "/" %>
<%= link_to "posts", posts_path %>
<%= link_to "new post", new_post_path %>

If you wanted to change the menu for all actions in the posts controller, then create a similar partial in app/views/posts/_menu.html.erb.

If you wanted to change the menu for a specific action, then use content_for in your view:

<% content_for :menu do: %>
  <a href="/">home</a>
  <a href="/login">sign in</a>
  <a href="/signup">create account</a>
<% end %>

Haml

I use Haml and I like it. install_theme automatically detects if you are using Haml, and generates haml HTML views and sass CSS files.

$ gem install drnic-haml --source http://gemcutter.org  # see below
$ rails my_haml_app
$ cd my_haml_app
$ haml --rails .
$ install_theme . path/to/theme/folder ".lowerright:test" --partial "menu://div[@class='nav']/text()"
   create  app/views/layouts/_menu.html.haml
   create  app/views/layouts/application.html.haml
   create  app/views/original_template/index.html.haml
   create  public/stylesheets/sass/style.sass

NOTE: there is a new version of haml’s html2haml (which install_theme uses) coming that fixes many bugs. In the short term, use the drnic-haml above.

Where’d my original content go?

Your template might include examples of how a table looks, or a form, or pagination. It would good if they weren’t lost on the chopping floor.

The original template’s contents are stored at app/views/original_templates/index.html.erb and viewable at http://localhost:3000/original_template

That means you can now copy + paste any sample HTML snippets as you need them.

How it works?

Look inside the generated application.html.erb file and you’ll see the following for each named partial:

<%= yield(:menu) || render_or_default('menu') %>

The yield(:menu) enables the content_for helper to override the partials.

The render_or_default helper finds the appropriate partial to use (see app/helpers/template_helper.rb for source).

The Future

Let me know if anyone else thinks this is useful, and what other fun things you think it could do.

Related posts:

1. First look at rails 3.0.pre This article is out of date in some aspects....
2. Rails themes can remember things I was getting annoyed at having to remember all the...
3. Closing in on The Dream: “one-click-to-deploy Rails apps” Got a simple app you want to build? Allocate...

Below are the slides and all the nice things people said about the talk, which has made me feel very good for sharing, and for the 60hr return flight from Brisbane to Toronto.

If you want to hear the jokes, and an Australian “mistaking” Canada for a state of America, perhaps wait for InfoQ to publish the video.

The slides

Nice things people said

Thanks to…

Elle Meredith who helped me design and theme the slides so they looked spot-on-awesome.

My two children for not being old enough to be disturbed by some of the things I said about them during the talk.

Today I actually found the thing. It’s red. The colour of the binding was my only chance to impose some sense of personalisation.

The title was The Morphing Architecture: Runtime Evolution of Distribute Applications. The abstract is too long to be bothered reciting here. Succinctly, as best I remember it, it could be:

If you have distributed applications (components owned by multiple organisations) that run 24×7, and you need to upgrade behaviour, how the hell do you sequence the live upgrade?

Like most PhDs, it is a project of theoretical usefulness, but not significantly close to any commercial interests so that some large company doesn’t solve all your interesting problems before you get around to writing a 200 page thesis.

In 220+ pages, the only interesting parts (to me now) are from my Acknowledgments section:

As [my parent's] eldest of two sons, I am that person in each family who is the “first experiment in parenting.”

The Acknowledgements section ended with this:

And finally [thanks]…
To all the people who ever came up to me…
    Asked me how my thesis was going…
        Laughed hideously…
            And ran off.

Ah, memories.

  me: What's on this weekend? Going to the football?
  me: Are you and Jackie still seeing each other?
  you: Yes
  me: Eh? Yes - football or yes to Jackie?

That is, eventually the messages become ambiguous as to which topic they go to.

The solution

A designer friend of mine and I discovered this problem every day as we talked about different projects and completely unrelated things. Ironically, this led to a new inline topic: what if each thread/topic could be visually identifiable?

Perhaps we could just modify one of the HTML-based IM clients, such as Gmail Chat/Gtalk (same could be done for Facebook’s IM client I guess), and use twitter-esque #tags to identify threads (no fancy jabber protocol changes). If we did this we could prototype something, see if it was a useful way to solve the multi-threaded IM chat problem. I mean, how hard could it be?

Prototype: Greasemonkey Script (Firefox + Safari)

Since I have a thing for Greasemonkey scripts at the moment (which also run on Safari/Mailplane using GreaseKit), it immediately came to mind as a way to hack into Gmail’s Chat.

After installing Greasemonkey or GreaseKit, click to install the extension for Gmail’s inline Jabber/Gtalk chat.

Restart Gmail, fire up a chat to someone (for example, complain of bugs to drnicwilliams@gmail.com) and try the following:

  greasemonkey is fun
  gmailchat is very nifty and hackable
  its cool that I can annotate gmail chat with #greasemonkey
  no way, #gmailchat is colour highlighted
  sexy

Which will look something like the picture at the top.

Sadly, I’m talking to myself here. QA testing can be a lonely man’s sport.

Success?

Technically, yes. I mean, it works. You use a different #tag and it will be a different colour.

It was a prototype to determine if using #tags was a friendly, non-invasive way to identify threads. And it kind-of works, as long as you remember to use them. In IM, less-so than twitter, it seems unnatural to add #tags, or prefix a keyword with a # character. But, in time, I think you’d learn to do it to get the benefit.

The bigger issue is that I don’t want to use Gmail’s Chat for my IM client. I didn’t find the source to Apple’s iChat client lying around on github; and I really don’t want to go hacking Cocoa/Win32 apps just to try out an idea. A greasemonkey script is an awesome way to try out something like this.

Now, if everyone could just make this idea of #tagging intra-IM conversation threads/topics, then perhaps 5 years from now Apple will pick it up and implement it in iChat. Any of the more accessible, open source clients could implement this too. Probably a lot sooner.

Known bugs

In Mailplane (though not Safari), the 2nd+ threads aren’t coloured differently. I’m having trouble fixing this at the moment due to an issue in blue-ridge’s setup on Safari.

It currently shares thread colouring across all open chat windows. Probably not a big issue. I forgot to consider multiple chat windows when I wrote the code.

When you use a new #tag, it only finds one previous message with ‘tag’ in it. Really, once a word is #tagged, then any message containing ‘tagged’ could be included in the thread.

Quirky thing I learned

You can’t really use the jquery.livequery.js plugin to watch for DOM changes in Greasemonkey scripts. It works by hooking into jQuery DOM modification calls, such as append and prepend, to know instantly that something has changed. Gmail, and many other websites, don’t use jQuery. So it doesn’t work. Even though your beautiful unit tests say it will. Use setInterval instead.

Project status

It’s finished. It was a prototype to try out an idea. It has unit tests, it works and if you want to use it for your own research project or “oh oh oh how cool would it be if…?” hackathon, go for gold with the code base. Rename it, abuse it. Have fun.

Source on github: http://github.com/drnic/threaded-gtalk-gmscript/

A pleasant word from my sponsor

When I was hacking on Threaded Gtalk GMScript, I wasn’t doing something more productive at my firm Mocra. Ironically, you could reward my wayward efforts by considering us for your awesome new Rails or iPhone project. It will make you happy. Especially if its chock-full of JavaScript.

Related posts:

1. TDD for Greasemonkey scripts; and introducing Ninja Search JS “this article shows how I used test-driven development tools and...
2. Yehuda Katz starts a blog Yehuda is the creator of autoDB – the wonderful admin...

Hopefully you can find good reasons to refer clients to myself and the crack-squad at Mocra. For example, we have had two client Rails projects appear in TechCrunch in 2009 (Orchestrate and Imindi). Also, our Oakley Surf Report iPhone app has appeared in Apple’s own TV commercials for the AppStore (first 10 secs of video below).

In the past, we’ve received lots of referrals but rarely have we gone beyond saying “thank you”. We think its time to put a dollar value on all our future “thank you”s. They are incredibly valuable to us, so we’d like to share some of the value.

To say thanks to you, we want to share 10% of the total consulting fees for any new client work as a referral incentive.

If we can help a friend or client of yours and we receive $10k in fees, then we’ll give you 10% or $1k. If we receive $250k, then we’ll give you $25k.

How to refer?

There’s no wrong way to ping us with a referral for a client we can potentially help.

One approach is to email me at referrals@mocra.com or on Skype at nicwilliams. We can quickly check if we’re able to help with the project, discuss anything interesting, and then contact the client.

Alternatively, you can give your friend/client our enquiry emails (rails@mocra.com or iphone@mocra.com), or skype at nicwilliams. Then you claim the referral via an email to referrals@mocra.com.

In the medium-term future, we’ll release a Referral Management system so you can see the status of your referrals, payments etc. Until then, use email to ask questions.

Receiving payments

In order to distribute payments to you, could you please email us at referrals@mocra.com with your contact details and either PayPal address or international banking details. Telepathic transfer of banking details nor referrals isn’t guaranteed to work. Emails are much more likely to succeed.

You are providing us with a valued service of marketing/advertising. We think you are awesome and will invite you to Christmas parties. Australian GST-registered businesses will have 10% GST added to payments.

Basic referral rules

Whilst we continue to draw up the fancy pants, small-print rules, some of the basic ones are:

• We’ll send out payments within a month of receipt of client payments.
• We don’t think you’re a bad person if your referral doesn’t hire us.
• In the event there is a dispute by 2+ claimants for a referral, the decision by me is final.
• You cannot work with or be a family member of Mocra nor the referred client.
• You are providing Mocra with a service. It makes us very happy. So we’re paying you for it.
• You may be required to send us a Tax Invoice for each amount payable (templates available).
• You can give away your referral income to charity or use it to fund open source development.
• We think you are awesome for reading this far, even if you never refer any work to us. Thanks for caring.

Happy developers

It makes us very happy to be contacted by new clients who tell us “I was told I should contact you.” Hopefully we can thank every referrer explicitly from now on. Thanks in advance.

Related posts:

1. Easy scheduling by location, tasks and people – a case study of a client application from Mocra UPDATE: Orchestrate was reported in TechCrunch Several years ago...