Contributing to Spotlight

Spotlight is a Rails engine and needs to be used in the context of a Rails application. We use engine_cart to create an internal test application.

Spotlight uses Solr as part of its integration tests. We use jettywrapper to manage the Solr instance used for development and test. We use a jetty instance preloaded with Solr maintained by projectblacklight.

Our rake ci and rake spotlight:server tasks use engine_cart and Solr automatically, but you can refer to engine_cart and jettywrapper documentation to work with these tools outside of those rake tasks.

Prerequisities

Ruby (2.2.0 or greater)
Java (7 or greater) for Solr
ImageMagick (http://www.imagemagick.org/script/index.php) due to carrierwave
PhantomJS (https://github.com/teampoltergeist/poltergeist#installing-phantomjs) - for testing javascript

One time setup

Install the prerequisites above.
Clone the spotlight git repo; cd in.
Ensure you will be using Ruby 2.2.0 or greater.
Install gems used by spotlight: $ bundle install

Note: if your system is confused by conflicting gem versions, you may need to add "bundle exec" to the beginning of each command, e.g. $ bundle exec rake engine_cart:generate. This ensures the command is run in the context of bundler's gem version management.

You may need to do the following:

$ rake jetty:download
$ rake jetty:unzip
$ rake jetty:environment

Running the test app

The spotlight:server rake task will build a Spotlight-based application, start Solr, and run the built-in rails server.

$ rake spotlight:server

Spotlight is now running at http://localhost:3000.

engine_cart builds the testing rails app at spec/internal by default.

Solr will run at http://localhost:8983/solr/blacklight-core by default.

If you wish to work with the testing rails app independently of Solr, see below.

To restart the test app (and Solr) in a pristine state:

$ rake jetty:stop
$ rake spotlight:server

Gotcha

Sometimes jetty doesn't shut down properly. You can check by seeing if jetty is running:

$ ps -eaf | grep jetty

If there is a jetty process running, you can stop it (from the top directory of the project) with

$ rake jetty:stop

Using Jetty Solr for Development

Spin up jetty:

$ rake jetty:start

Shut down jetty when done:

$ rake jetty:stop

Reset jetty to pristine state (e.g. remove Solr docs):

$ rake jetty:clean
$ rake spotlight:configure_jetty

Spin up testing Rails app

$ rake engine_cart:generate

creates a pristine testing Blacklight Rails app for spotlight at spec/internal.

You will need an initial admin user:

$ cd spec/internal
$ rake spotlight:initialize

And then you can start the rails testing app (from spec/internal):

$ rails s

Spotlight is now running at http://localhost:3000.

Note that the testing app is expecting Solr to be running.

You can change the testing app's location - refer to the engine_cart documentation.

Spotlight Fixtures

You may want to add the spotlight fixtures to Solr (from spec/internal):

$ rake spotlight_test:solr:seed

Clean Out Testing Rails Application

To clean out the testing app: (from top level directory)

$ rake engine_cart:generate

Running the tests

The ci rake task will build a Spotlight-based application, start Solr, run the tests, and then shut down Solr when the tests are finished. Solr should not be running already when you run the tests.

$ rake jetty:stop
$ rake ci

See Testing for more information.

Running rubocop

rubocop is used to enforce consistent coding style, and is part of the spotlight travis continuous integration build. $ rake rubocop (from the top level) will show anything flagged by rubocop as non-conformant.

Making Your Changes

Fork the project.
Start a feature/bugfix branch.
Commit and push until you are happy with your contribution.
Make sure to add tests for it. This is important so we don't break it in a future version unintentionally.
After making your changes, be sure to run the Spotlight tests to make sure everything works.
Make sure your changes pass rubocop.
Submit your change as a Pull Request.