Hacking SproutCore

Hacking SproutCore is easy and fun.

If you’re writing a SproutCore application and you would like to see a bug fixed or a new feature added, you can get a copy of the framework yourself, make your fixes/improvements, and send a patch back to the community to be included in the next public release of SproutCore.

NOTE: You must have git installed in order to hack on SproutCore. For installation instructions, please visit Git – Fast Version Control System.

An introductory tutorial outlines the basic commands and concepts.

Step 1: Prepare your development environment

This tutorial assumes you are working on a SproutCore-based project and want to make some changes to SproutCore related to your project. If you do not have a specific project, you can always work in the SproutCore-Samples test harness. To get the SproutCore Samples, do the following on the command line:

$ git clone git://github.com/sproutit/sproutcore-samples
... output will clone the samples
$ cd sproutcore-samples
$ git submodule init
$ git submodule update
$ cd frameworks/sproutcore
$ git checkout master

Step 2: Get the framework code

When you get the SproutCore build tools from RubyGems, it includes a version of the SproutCore JavaScript that is available system wide. To make changes, however, you will need to get an editable copy of the framework and install it in your project.

If you are using the sproutcore-samples project, then this is done for you. If you are working with your own project (and not using the sproutcore-samples), do the following:

$ cd MY-PROJECT (the directory with an sc-config.rb file in it)
$ sc-install sproutcore

This will check out a copy of the SproutCore JavaScript into your frameworks directory. Now, just restart your instance of sc-server and it should automatically load the editable version of SproutCore instead of the one installed with RubyGems.

Step 3: Make some changes!

Now the fun part. Fix a bug. Add a feature! Edits you make to the framework you have just checked out will appear immediately when you refresh the page in your client.

Before you make any major changes, we usually recommend that you switch to a new local branch in Git. This way you can save your changes, but revert to an unaltered version of SproutCore anytime you want. To switch to a branch, do the following before you begin making changes:

$ cd MY-PROJECT/frameworks/sproutcore
$ git checkout -b BRANCH-NAME

You can name the branch anything you want. Usually you will name it after the kind of fix you are making. For example git checkout -b add-commodore-64-support would save your changes on the branch add-commodore-64-support.

Later on, if you ever need to switch back to a clean version of SproutCore, you can do the following:

$ cd MY-PROJECT/frameworks/sproutcore
$ git commit -a -m"Commit message to save any pending changes" 
$ git checkout master

When you are ready to return to your edited version, just checkout your branch again:

$ cd MY-PROJECT/frameworks/sproutcore
$ git checkout BRANCH-NAME

Step 4: Run some tests

Once you have made your change, you should run all the tests at http://localhost:4020/sproutcore/-tests. Make sure they all pass. If you are adding a new feature or fixing a nasty bug, you should consider adding a test for your fix as well. Most changes will not be accepted unless it is covered by a new or existing test. (To test documentation, rebuild the docs and make sure they generate properly).

Be sure you run your tests on at least Firefox and Safari. IE7 will soon become a requirement as well. For more information, see Unit Testing.

Step 5: Submit a patch

Now you are ready to share your code! To submit your change, just create a patch and then submit it as a ticket. Creating a patch to submit is really easy in git. Just type the following:

$ cd MY-PROJECT/frameworks/sproutcore
$ git commit -a -m"Write a message explaining your fix" 
$ git format-patch HEAD^

This will generate patch files for a commit that you can attach to a ticket for inclusion in the framework. Visit our “Lighthouse ticket system”: http://sproutit.lighthouseapp.com/projects/11697-sproutcore and open a new ticket. Describe your fix and include your patch. Don’t forget to include the tests!

Step 6: Getting the latest updates from SproutCore

When changes are made to the main SproutCore branch, you can automatically update those changes in your own repository. Just do the following:

$ cd MY-PROJECT/frameworks/sproutcore
$ git checkout master
$ git pull

You will now have a pristine copy of the latest version of SproutCore from the head of Git. If you have made changes on your own branch and you would like to merge updates to SproutCore into your own branch, you can then do the following:

$ cd MY-PROJECT/frameworks/sproutcore
$ git checkout BRANCH-NAME
$ git merge master

Step 7: Update SproutCore and celebrate your newfound fame

We try to process patch submissions as quickly as possible. If other changes have made it in since you submitted your patch that prevent your patch from being applied, we may ask you to update your SproutCore code and rebuild the patch. This way you can make sure your fix works.

Related Links

Add related links here.

Comments

How do you hack sproutcore with the latest sproutcore-buildtools ?