Contributing to Thinking Sphinx

Forking and Patching

If you’re offering a patch to Thinking Sphinx, the best way to do this is to fork the GitHub project, patch it, and then send me a Pull Request. This last step is important – while I may be following your fork on GitHub, the request means an email ends up in my inbox, so I won’t forget about your changes.

Do not forget to add specs – and features, if there’s any functionality changes. This keeps Thinking Sphinx as stable as possible, and makes it far easier for me to merge your changes in.

Sometimes I accept patches, sometimes I don’t. Please don’t be offended if your patch falls into the latter category – I want to keep Thinking Sphinx as lean as possible, and that means I don’t add every feature that people request or write.

Dependencies

Thinking Sphinx’s specs are written with RSpec, and the integration tests with Cucumber, so you’ll need both of these gems installed for starters. You’ll also want to install YARD, RedCloth and BlueCloth for documentation, and Jeweler for gem management and useful rake tasks.

gem install rspec cucumber bluecloth RedCloth yard

Running Specs

The specs for Thinking Sphinx require a database connection – and currently will only talk to a database called thinking_sphinx. The host defaults to localhost, the username thinking_sphinx, and no password. If you want to customise these settings, create a YAML file named spec/fixtures/database.yml. You can find a sample file at spec/fixtures/database.yml.default.

host: localhost
username: root
password: secret

Depending on which version of Sphinx you have installed, you will also want to invoke the specs with the VERSION environment variable set. Here’s an example:

rake spec VERSION=0.9.9

Running Cucumber Features

Thinking Sphinx’s Cucumber features require both a database, and port 9312 to run Sphinx on. The latter should take care of itself provided you’re not using that port already. The former is managed by features/support/database.yml (with an example file at features/support/database.example.yml).

And again, just like with the specs, you’ll need to run the features with a given version specified:

rake features:mysql VERSION=0.9.9

There are features tasks for both mysql and postgresql, and the base task runs both, one after the other. You will need the same authentication details for in each database system if you’re running the feature set on both.

Writing Third-Party Gems

If you’re writing gems that hook into Thinking Sphinx, I highly recommend you write specs that don’t interact with Sphinx or a database if possible (via mocks and stubs), and then use Cucumber for integration tests that interact with Sphinx.

For the latter, Thinking Sphinx provides a Cucumber World class to make things pretty seamless. Firstly, your features/support/env.rb should look something like the following:

require 'rubygems'
require 'cucumber'
require 'spec/expectations'
require 'fileutils'
require 'active_record'

$:.unshift File.dirname(__FILE__) + '/../../lib'

require 'cucumber/thinking_sphinx/internal_world'

world = Cucumber::ThinkingSphinx::InternalWorld.new
world.configure_database

SphinxVersion = ENV['VERSION'] || '0.9.8'

require "thinking_sphinx/#{SphinxVersion}"
require 'path/to/thinking_sphinx/extension'

world.setup

This World expects four things:

  • Database migrations in features/support/db/migrations
  • Models in features/support/models
  • Ruby fixtures (for setting up model instances) in features/support/db/fixtures
  • Database configuration in features/support/database.yml

The default database settings are:

  • Adapter: mysql
  • Host: localhost
  • Database: thinking_sphinx
  • Username: thinking_sphinx

You can customise all of these settings via accessor methods on the instance of the InternalWorld in your env.rb file.

I recommend looking at the Delayed Delta library for inspiration.