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.
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.
The specs for Thinking Sphinx require a database connection - and
currently will only talk to a database called
host defaults to
localhost, the username
thinking_sphinx, and no
password. If you want to customise these settings, create a YAML file
spec/fixtures/database.yml. You can find a sample file at
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:
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
And again, just like with the specs, you’ll need to run the features with a given version specified:
There are features tasks for both
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
look something like the following:
This World expects four things:
- Database migrations in
- Models in
- Ruby fixtures (for setting up model instances) in
- Database configuration in
The default database settings are:
You can customise all of these settings via accessor methods on the
instance of the InternalWorld in your
I recommend looking at the Delayed Delta library for inspiration.