About the Author
Peter Berkenbosch is a Senior Developer and Technical Account Manager at Spree Commerce. He loves programming in dynamic languages such as Ruby, and mostly uses Ruby when developing web applications with the Rails framework.
In this small guide I will share the setup I use to contribute to Spree Commerce.
*Disclaimer: This post contains some content written by me and others for the developer guides at Spree Commerce.
Fork and setup upstream remote
Fork the Spree repository on github and clone the spree project on your local machine:
Make sure to run the tests. Spree is only taking pull requests with passing tests, and it’s great to know that you have a clean slate:
To setup the upstream branch to get the changes back from spree/spree you will need to setup a new remote for your repository. I always call this remote `upstream`. To setup spree/spree as an upstream remote you need to tell git about it like this:
Get Changes from Upstream Remote
When you need to get the changes in the spree/spree repository into your own fork I use this small script called `gitub`. You can find it on my dotfiles repository.
When you’re on the master branch, it will fetch all the changes from the upstream remote, rebase the upstream branch into your local master branch and then push it to your fork on github.
Create a new topic branch then make changes and add tests for your changes. Only refactoring and documentation changes require no new tests. If you are adding functionality or fixing a bug, we need tests!
Push to your fork and submit a pull request. If the changes will apply cleanly to the latest stable branches and master branch, you’ll only need to submit one pull request.
If a PR does not apply cleanly to one of its targeted branches, then a separate PR should be created that does. For instance, if a PR applied to master & 2-1-stable but not 2-0-stable, then there should be one PR for master & 2-1-stable and another, separate PR for 2-0-stable.
Git branches are “cheap.” Creating branches in Git is incredibly easy and it’s an ideal way to isolate a specific set of changes. By keeping a specific set of changes isolated, it will help us to navigate your fork and apply only the changes we’re interested in. You should create a clean branch based on the latest spree/master when doing this. It’s important you follow these steps exactly, it will prevent you from accidentally including unrelated changes from your local repository into the branch.
For example, if we were submitting a patch to fix an issue with the CSS in the flash error message you could create a branch as follows:
The fetch command will grab all of the latest commits from the Spree master branch. Don’t worry, it doesn’t permanently alter your working repository and you can return to your master branch later. The track part of the command will tell git that this branch should track with the remote version of the upstream master. This is another way of saying that the branch should be based on a clean copy of the latest official source code (without any of your unrelated local changes).
You can then do work locally on this topic branch and push it up to your GitHub fork when you’re done. So in our previous example we do something like:
Provide solid and clear commit messages so we can read from the commit what is fixed or added in this specific pull request.
When developing in the topic branch it’s a best practice to commit a lot with small changes. However, some of those commit messages are noise the moment they turn into a pull request. You should rebase and squash the noise commits. For example:
Rebase and squash this into:
When you’re done your work in the topic branch, rebase the topic branch against master (or the stable branch you’ve forked from)
Sample git rebase:
This will show you this next screen:
To make this neat you can do something like this:
The next screen will give you the ability to reword the 5 commits into one neat one.
For Larger Pull Request Create an Empty PR with a To Do List
Follow the link to see more information on how to create a task list.
To view this post in its original format, as well as more helpful guides and tips, visit the blog of Peter Berkenbosch.