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 solr_wrapper to manage the Solr instance used for development and test, using the Solr schema and configuration distributed with the project.

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

Prerequisities

1. Ruby (2.2.0 or greater)
2. Java (8 or greater) for Solr
3. ImageMagick (http://www.imagemagick.org/script/index.php) due to carrierwave

One time setup

1. Install the prerequisites above.
2. Clone the spotlight git repo; cd in.
3. Ensure you will be using Ruby 2.2.0 or greater.
4. 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.

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:

$ solr_wrapper
$ rake engine_cart:server

Gotcha

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

$ ps -eaf | grep solr

Using Jetty Solr for development

Spin up solr (in a new tab or window):

$ solr_wrapper

Reset solr to pristine state (e.g. remove Solr docs, core, etc):

$ solr_wrapper clean

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 .internal_test_app
$ 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 expects 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:regenerate

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 ci

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.