Spree is an open source project. Anyone can use the code, but more importantly, anyone can contribute. This is a group effort and we value your input. Please consider making a contribution to help improve the Spree project. This guide covers:
- How to file a ticket when you discover a bug
- How to contribute fixes and improvements to the core
- Information on how to improve the documentation
endprologue.
Spree is an open source project and as such contributions are always welcome. Our community is one which encourages involvement from all developers regardless of their ability level. We ask that you be patient with the other members of the community and maintain a respectful attitude towards other people’s work. Open source is a great way to learn a new technology so don’t be afraid to jump right in, even if you are new to Ruby/Rails.
WARNING. We have an official contribution policy. Please not just send us Github pull requests – they will be ignored. We will happily accept your contribution but please read this document carefully before contributing.
The core is the basic foundation of the Spree project. It is maintained in Github under the spree/spree project. There is a core team of developers who are responsible for maintaining the quality of the source code. Your changes will ultimately need to be merged into the official project by a core member. Thanks to Github, however, you do not have to wait for a core member to get started with your fix.
Please perform the following one time steps for your fork in Github.
You will need to create a fork of the Spree project in Github. This is a pretty self explanatory process. After you have done this and cloned your repository you will need to add a reference to the official repository (railsdog).
git remote add railsdog git://github.com/spree/spree.git
WARNING. Its important that you add this reference. Its a one time step that will allow you to easily create branches based on the most recent version of the official code.
The Spree development team is using Light House for tracking all issue and feature requests. Use it to browse the existing tickets or to submit a new issue. All changes to the core should flow through this system. Please file an issue before you commit your code so that you can then reference the issue number in your commit. We get a high volume of contributions, so taking a second to create the LH issue helps us to keep track of your bug reports and fixes so that they do not get lost in the shuffle.
WARNING. Do not submit pull requests in Github. Do not send bug reports to the spree-user list. In both cases you will be politely asked to file an issue in Lighthouse. We need to deal with these matters in the most efficient way possible – we’re not trying to be difficult.
Git branches are “cheap.” Creating branches in Git is incredibly easy and its an ideal way to isolate a specific set of changes. You may be fixing several things at one time but by keeping your changes isolated it will help us to find and apply only the changes we’re interested in. You should create a clean branch based on the latest railsdog/master when doing this. It is important you follow these steps exactly, it will prevent you from accidentally including unrelated changes from your local copy into the branch.
For example, if we were submitting a patch to issue #525 which provided thai localization we would create the branch as follows:
git fetch railsdog
git checkout -b 525-add-thai-localization —track railsdog/master
The fetch command will grab all of the latest commits on railsdog. Don’t worry, it doesn’t merge them into your current branch or anything. This is just making sure that you have a complete copy of the railsdog source. The commits will be stored behind the scenes, your local code will remain as it was.
The track part of the command will tell git that this branch should track with the remote version of railsdog master. This is another way of saying that the branch should be based on a clean copy of the latest source code.
When you’re ready to commit be sure to add the issue number in your commit message. It is suggested that you just use git commit without the -m option. This will allow you to view the commit message in your editor and add some line spacing for readability. Here’s an example of a commit message.
Provided a Thai localization.
[#525]
Please be sure to include the issue number inside of brackets. This will make sure that Lighthouse will be notified of the changeset when you push to Github. It will also automatically change the ticket state to “patched” which will help us to prioritize issues where users have supplied a fix. Note also the blank line between the comment and the issue number. This helps with readability.
WARN. Lighthouse will not be notified of the fix automatically due to some technical problems with the hook. Please continue to use this notation since the style will be compatible with the eventual new solution to this problem.
If you’ve been working on your fix for more than a few hours there is a good chance that you will need to rebase. Git’s rebase command is one of those scary sounding things that really isn’t all that bad once you understand it.
So you can check to see if there have been any chances to railsdog since you created your branch.
git fetch railsdogIf nothing comes back, then railsdog/master is unchanged and there’s nothing to do. If you see a bunch of commits coming down, however, then its time to rebase. Run the following command from your “issue branch” which you should still be on.
git rebase railsdog/masterIf you’re lucky the command will run without incident. If there are conflicts, you can resolve them manually (better you then us) and continue the rebase operation (+git rebase —continue).
Now all you have to do is push your changes to a remote branch in Git Hub.
git push origin 525-add-thai-localization
If you have set up the GitHub service hook as described earlier, the changes will automatically be reflected in the Lighthouse ticket once you push.
WARNING. In previous versions of this guide we encouraged you to create a “service hook” for your fork in Github. Unfortunately we are expereincing technical problems processing these commit messages. We’re working on a new solution that will automatically detect your fixes in Github when using the proper notation in your commits.
The final step is to make sure these changes are merged back into your own master branch. This way they are available to you alongside your other changes that may or may not be slated to be merged into the core.
So continuing with our previous example you should then do:
git checkout master git merge 525-add-thai-localization git push origin master- Create a ticket in Lighthouse
- Create a branch for each ticket
- Note the ticket # in your commit
- Rebase against the latest railsdog/master
- Push the commit to your remote branch
- Merge the commit to your master and push to Github
Improvements to the documentation is encouraged. The primary source of documentation are the guides (HINT: You are reading one now.) The documentation is in its own GitHub project called spree-guides. To build the documentation normally simply clone and install.
$ git clone git://github.com/spree/spree-guides.git $ cd spree-guides $ rake guidesINFO. You will also need to install the RedCloth gem (4.1.1 or greater) if you do not done so.
You do not need to fork the spree-guides project in order to contribute. Just send an email to spree-user (be sure to include your github username) and say that you would like to contribute. We’ll add you to the list so you can commit directly to the guides project.
INFO. If you’re uncomfortable using Git, etc. you can report a mistake in the Spree guides using Github’s built in issue tracker. Please do not report issues with the documentation in the Lighthouse ticket system which is reserved for reporting bugs in the code.
WARNING. Please be considerate when making changes to the spree-guides. If you wish to make major changes to how the documentation is organized then you should use a GitHub fork and ask people to review your proposed changes instead.
Extensions include specialized functionality that is provided as a third party add-on to Spree. We’re in the process of implementing guidelines for contributing to extensions. Please check back later for more detailed guidelines.