layout | title |
---|---|
ts_en |
Contributing to Thinking Sphinx |
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.
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.
{% highlight sh %}
gem install rspec cucumber bluecloth RedCloth yard
{% endhighlight %}
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
.
{% highlight yaml %}
host: localhost
username: root
password: secret
{% endhighlight %}
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:
{% highlight sh %}
rake spec VERSION=0.9.9
{% endhighlight %}
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:
{% highlight sh %}
rake features:mysql VERSION=0.9.9
{% endhighlight %}
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.
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:
{% highlight ruby %}
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
{% endhighlight %}
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.