Developing spree
This guide covers all the necessary steps to contributing to Spree source code. We’re happy you’re here!
Developing Spree
Spree codebase
Spree API is written in Ruby on Rails framework and is mounted into a Rails application as a Rails Engine.
Spree namespace
All Spree models, controllers and other Ruby classes are namespaced by the Spree
keyword, eg. Spree::Product
. This means that those files are also located in spree
sub-directories eg. app/models/spree/product.rb.
Forking Spree repo
Go to Spree GitHub repository and click the Fork button. This will create a copy of the Spree repository on your GitHub account. See Github Documentation for more information on forking.
Local setup
-
Clone your fork repository
git clone git://github.com/your_github_username/spree.git cd spree
-
Install required libraries
You will need SQLite (or PostgreSQL or MySQL) and libvips installed on your system. You can install them using the following commands:
brew install vips
If you are using Ubuntu or Windows Linux Subsystem, you can install libvips using the following command:
sudo apt-get install libvips
Please refer to the libvips installation guide for more information.
-
Install the gem dependencies
bundle install
Creating Sandbox application
Bellow command will setup a Rails application with Spree pre-installed with some data seeded:
bin/sandbox.sh
By default, Sandbox uses the SQLite database. But you can switch to PostgreSQL or MySQL:
DB=postgres bin/sandbox.sh
Performance in development mode
You may notice that your Spree store runs slower in development environment. This is caused by disabled caching and automatic reloading of code after each change.
Caching
Caching is disabled by default. To turn on caching please run:
bin/rails dev:cache
You will need to restart rails server after this change.
Making changes
Create a new branch for your changes. Do not push changes to the main branch. Branch name should be human-readable and informative, eg.
- bug fixes:
fix/order-recalculation-total-bug
- features:
feature/my-new-amazing-feature
Running Tests
We use CircleCI to run the tests for Spree.
You can see the build statuses at https://circleci.com/gh/spree/spree.
Each gem contains its own series of tests, and for each directory, you need to do a quick one-time creation of a test application and then you can use it to run the tests. For example, to run the tests for the core project.
cd core
bundle exec rake test_app
bundle exec rspec
If you would like to run specs against a particular database you may specify the dummy app’s database, which defaults to sqlite3.
DB=postgres bundle exec rake test_app
If you want to run specs for only a single spec file
cd core
bundle exec rspec spec/models/spree/state_spec.rb
If you want to run a particular line of spec
cd core
bundle exec rspec spec/models/spree/state_spec.rb:7
If a large number of tests fail when you run rspec for the first time, confirm that you have Redis installed and running. You can use the command brew services info redis
to check if Redis is running. If it is not running, start Redis with brew services start redis
.
Running integration tests on MacOS (only applicable for Admin Panel)
We use chromedriver to run integration tests. To install it please use this command:
brew cask install chromedriver
Submitting Changes
Please keep your commit history meaningful and clear. This guide covers it quite well and we recommend reading it, not only for Spree project but for any IT project overall.
-
Push your changes to a topic branch in your fork of the repository.
git push -u origin fix/order-recalculation-total-bug
-
Create a Pull request - please follow this guide
If your changes references Github issues, please mark which issue you’re fixing by adding
Fixes #<number or url of the issue>
in the commit name or PR title/description. This will automatically mark that issue as closed when your PR will be merged. -
Wait for CI to pass
-
If CI passed wait for Spree Core team code review
We’re aiming to review and leave feedback as soon as possible. We’ll leave you a meaningul feedback if needed.
Troubleshooting
This section will help you troubleshoot common issues with Spree.
libvips error
If you are using Spree 4.5 or higher, you may encounter the following libvips error:
LoadError: Could not open library 'vips.so.42'
This error is usually an indication that you do not have libvips installed locally on your machine. Check that libvips is installed with vips -v
, and if it is not installed, follow installation instructions here.
That’s a wrap!
Thank you for participating in Open Source and improving Spree - you’re awesome!
Was this page helpful?