<commit_before>h2. Working with the Source Code

This guide covers obtaining and running the source code.  This is primarily for developers who are interested in contributing code to the Spree project or fixing the source code themselves.  It is not necessary to have a copy of the source code to run Spree.  

endprologue.

h3. Git

The Spree source code is currently maintained in a "Git":http://git.or.cz/ repository. Git is a distributed version control system (DVCS) and it allows us to do things never before possible with SVN. If you're skeptical of Git just remember how skeptical you were of SVN when you were using CVS. The differences are subtle but important and they are best understood by hands on use.

The authoritative git repository is hosted by "GitHub":http://github.com/ and is located "here":http://github.com/railsdog/spree/tree/master. You can clone the git repository using the following command:

<shell>
git clone git://github.com/railsdog/spree.git spree 
</shell>

INFO. If you are planning on contributing to Spree you should create a fork through Git Hub and push fixes to clearly labelled branches (see the "Contributors Guide":contributing_to_spree.html for details.)

NOTE. If the official GitHub repo is down you can try our mirror at "repo.or.cz":http://repo.or.cz

h4. Browsing the Repository and/or Downloading the Source Code

You can easily browse the repository through Git Hub's excellent "visual interface":http://github.com/railsdog/spree/tree/master. Git Hub also contains a link to download a tarball copy of the latest source code as well as links to "previous versions":http://github.com/railsdog/spree/downloads.

h4. Git on Windows

There are some well developed Git clients for Windows now. If you are on a Windows box you might want to check out the "msygit":http://code.google.com/p/msysgit/ project. There is also a "screencast":http://gitcasts.com/posts/git-on-windows available.

h4. SVN

There are no immediate plans to support SVN clients. Given that most of the Rails world is moving to git (including the RoR project itself) maybe this is the time for you to jump on the bandwagon.

h4. Monitoring Changes in the Source

If you would like to keep up to date on changes to the source you can subscribe to the github 
"RSS feed":http://github.com/feeds/railsdog/commits/spree/master and you will be notified of all the commits.

h3. Building the Gem from the Source

h4. Motivation

Why bother building the Spree gem from the source?  The primary answer is that it allows you to take advantage of all of those great "edge" features without having to wait for the next official release of Spree, and to have this same version of Spree running in all of your projects.

In order to create a new Spree application you will need to run +spree <app-name>+ which is invoked using the currently installed Spree gem.  The +spree+ command is also responsible for setting up your applications' environment settings, etc. so if you're trying to build a new store with the cutting edge features, you'll want to build the gem locally.

INFO. Another possibility is "vendor" mode, where a copy of Spree is stored inside your app at location +vendor/spree+. You can install specific versions or revisions of Spree here: many people use the git submodule feature to track a precise version of Spree inside their projects. The disadvantage is that two projects may not be running the exact same version, i.e. you have to check manually.

h4. Prerequisites

# Rails 2.3.x 
# Ruby Gems 1.3.6 or greater
# Spree gem dependencies (run +rake gems+ to check, +rake gems:install+ to install)
# The Jeweler gem (which pulls in a Git gem and Gemcutter too - use +(sudo) gem install jeweler+)

INFO. Gem building no longer runs all of the tests.

NOTE. It is suggested that you get Spree up and running using the source first before attempting to build the gem.  This will be the easiest way to make sure you have all of the correct dependencies, etc.

h4. Performing the Actual Build

First, you should create/update the gemspec. You must have the Jeweler gem installed for this.

Use the following command to build the gem

<shell>
rake build
</shell>

Now you can install the gem, replacing X,Y,Z with the appropriate numbers

<shell>
sudo gem install pkg/spree-X.Y.Z.gem  
</shell>

NOTE. The exact version of the gem will correspond to whatever version reflects the state of the edge code at the time you build it._

h4. Considerations

* An edge gem will have a x.y.99 version number.  This denotes an "edge" version.  You may need to uninstall the edge gem later if you want to work with the x.y.z gem once it is released.

* If you want to deploy the gem on multiple machines: the built gem is in the spree source directory, in +pkg/+. Just copy it and install it, eg +sudo gem install spree-0.8.99.gem+

* You may want to do  +rm -rf pkg+ to clean things up from previous build attempts before building the gem again.

<commit_msg>Minor additions to source guide.<commit_after>h2. Working with the Source Code

This guide covers obtaining and running the source code.  This is primarily for developers who are interested in contributing code to the Spree project or fixing the source code themselves.  It is not necessary to have a copy of the source code to run Spree.  This guide covers the following topics:

* How Spree uses Git and Github to manage source code
* The various gems that comprise the Spree source code
* Building the gem from the source

endprologue.

h3. Git

The Spree source code is currently maintained in a "Git":http://git.or.cz/ repository. Git is a distributed version control system (DVCS) and it allows us to do things never before possible with SVN. If you're skeptical of Git just remember how skeptical you were of SVN when you were using CVS. The differences are subtle but important and they are best understood by hands on use.

The authoritative git repository is hosted by "GitHub":http://github.com/ and is located in the  "railsdog":http://github.com/railsdog/spree/tree/master repository. You can clone the git repository using the following command:

<shell>
git clone git://github.com/railsdog/spree.git
</shell>

INFO. If you are planning on contributing to Spree you should create a fork through Git Hub and push fixes to clearly labelled branches (see the "Contributors Guide":contributing_to_spree.html for details.)

NOTE. If the official GitHub repo is down you can try our mirror at "repo.or.cz":http://repo.or.cz

h4. Browsing the Repository and/or Downloading the Source Code

You can easily browse the repository through Git Hub's excellent "visual interface":http://github.com/railsdog/spree/tree/master. Git Hub also contains a link to download a tarball copy of the latest source code as well as links to "previous versions":http://github.com/railsdog/spree/downloads.

h4. Git on Windows

There are some well developed Git clients for Windows now. If you are on a Windows box you might want to check out the "msygit":http://code.google.com/p/msysgit/ project. There is also a "screencast":http://gitcasts.com/posts/git-on-windows available.

h4. SVN

There are no immediate plans to support SVN clients. Since most of the Rails community is using git SVN support is not really a priority.

h4. Monitoring Changes in the Source

If you would like to keep up to date on changes to the source you can subscribe to the github
"RSS feed":http://github.com/feeds/railsdog/commits/spree/master and you will be notified of all the commits.

h3. Bundler

Spree uses the very excellent "bundler":http://gembundler.com/ gem to manage its dependencies.  We are assuming you have basic familiarity with bundler.  A detailed explanation of bundler is beyond the scope of this guide.

You can install the gem dependencies using bundler as follows:

<shell>
  bundle install
</shell>

The standard +Gemfile.lock+ is also included in the source so you can be sure that you're using the exact same versions of the gem dependencies used by the core team.

h3. Organization of the Source Code


h3. Building the Gem from the Source

h4. Motivation

Why bother building the Spree gem from the source?  The primary answer is that it allows you to take advantage of all of those great "edge" features without having to wait for the next official release of Spree, and to have this same version of Spree running in all of your projects.

In order to create a new Spree application you will need to run +spree <app-name>+ which is invoked using the currently installed Spree gem.  The +spree+ command is also responsible for setting up your applications' environment settings, etc. so if you're trying to build a new store with the cutting edge features, you'll want to build the gem locally.

INFO. Another possibility is "vendor" mode, where a copy of Spree is stored inside your app at location +vendor/spree+. You can install specific versions or revisions of Spree here: many people use the git submodule feature to track a precise version of Spree inside their projects. The disadvantage is that two projects may not be running the exact same version, i.e. you have to check manually.

h4. Prerequisites

# Rails 2.3.x
# Ruby Gems 1.3.6 or greater
# Spree gem dependencies (run +rake gems+ to check, +rake gems:install+ to install)
# The Jeweler gem (which pulls in a Git gem and Gemcutter too - use +(sudo) gem install jeweler+)

INFO. Gem building no longer runs all of the tests.

NOTE. It is suggested that you get Spree up and running using the source first before attempting to build the gem.  This will be the easiest way to make sure you have all of the correct dependencies, etc.

h4. Performing the Actual Build

First, you should create/update the gemspec. You must have the Jeweler gem installed for this.

Use the following command to build the gem

<shell>
rake build
</shell>

Now you can install the gem, replacing X,Y,Z with the appropriate numbers

<shell>
sudo gem install pkg/spree-X.Y.Z.gem
</shell>

NOTE. The exact version of the gem will correspond to whatever version reflects the state of the edge code at the time you build it._

h4. Considerations

* An edge gem will have a x.y.99 version number.  This denotes an "edge" version.  You may need to uninstall the edge gem later if you want to work with the x.y.z gem once it is released.

* If you want to deploy the gem on multiple machines: the built gem is in the spree source directory, in +pkg/+. Just copy it and install it, eg +sudo gem install spree-0.8.99.gem+

* You may want to do  +rm -rf pkg+ to clean things up from previous build attempts before building the gem again.


{'fraction_non_alphanumeric': 0.0531015037593985, 'fraction_numerical': 0.004323308270676692, 'mean_word_length': 4.0312056737588655, 'pattern_counts': {'":': 21, '<': 19, '<?xml version=': 0, '>': 19, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4102314', 'n_tokens_mistral': 2882, 'n_tokens_neox': 2763, 'n_words': 1679}