<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.  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  "spree":http://github.com/spree/spree/tree/master repository. You can clone the git repository using the following command:

<shell>
$ git clone git://github.com/spree/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/spree/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/spree/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.

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/spree/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. Layout and Structure

h4. Collection of Gems

The Spree gem itself is very minimal and consists mostly as a collection of gems.  These gems are maintained together in a single Github repository and new versions of the gems are shipped with each new Spree release.  The official documentation (which you are reading now) covers functionality provided by each of these gems.|

Within the Spree source, each of the gems is organized into subdirectories as follows:

|_<.Gem|_.Directory|_.Description|
|spree_api|api|Provides REST API access|
|spree_auth|auth|Provides authentication and authorization (via authlogic and cancan gems)|
|spree_core|core|Core functionality - all other gems depend on this gem|
|spree_dash|dash|Simple overview dashboard|
|spree_promo|promo|Coupons and promotions|
|spree_sample|sample|Sample data and images|

h4. Use of Rails Engines

Each of the gems in Spree makes use of Rails Engines.  This functionality was introduced in Rails 3.0 and allows Engines to behave in a manner similar to fully-functional applications.  Relying on this mechanism provides several advantages:

h5. An Intuitive Mechanism for Customization

Default Spree functionality is provided via the Rails engine gems.  Engines can provides several aspects traditionally associated with a Rails application including (but not limited to):

* Models, views and controllers
* Routes
* Helpers
* Rake tasks
* Generators
* Locales

All of these elements can be overridden in the main Rails application.  Therefore, it is relatively simple to add Spree to your Rails application and then customize it further by supplying your own elements in that same application. A full discussion of Rails Engines is not appropriate here.  Please consult the Rails Guides for more information.

h5. Simple Distribution and Installation as Gems

Using a Spree gem is as simple as adding it to your +Gemfile+ (ie. very simple)

<shell>
  gem 'spree-core', '0.30.0'
</shell>

Distribution of Spree (and its extensions) is also consistent with Rails standards and modularity (see next.)

h5. Consistency With a Rails Standard

Prior to version 0.30.0, Spree used a complex custom mechanism for implementing "engine-like" functionality.  While it was difficult to strip this functionality out of Spree the benefits are well worth it.  Spree will now receive all of the massive testing and attention to detail that comes for free when using the Rails core.

h5. Modularity

There are differing opinions on what belongs in the "core."  People are often expressing their opinion that Spree is either "getting too fat" or "lacks basic features."  By relying on these engines (and distributing them as gems), developers are free to use only the parts of Spree that they find useful.  For instance, this would allow you to omit promotions functionality or to replace the authentication mechanism.

WARNING: The engine architecture is a work in progress.  Some of the modularity described above is theoretical and yet to be tested in a real world application.  Expect minor difficulties if you decide to use a subset of the Spree gems (although we would gladly work with you to resolve them.)

h3. Building a Sandbox Application<commit_msg>Correct another reference to spree-core<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  "spree":http://github.com/spree/spree/tree/master repository. You can clone the git repository using the following command:

<shell>
$ git clone git://github.com/spree/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/spree/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/spree/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.

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/spree/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. Layout and Structure

h4. Collection of Gems

The Spree gem itself is very minimal and consists mostly as a collection of gems.  These gems are maintained together in a single Github repository and new versions of the gems are shipped with each new Spree release.  The official documentation (which you are reading now) covers functionality provided by each of these gems.|

Within the Spree source, each of the gems is organized into subdirectories as follows:

|_<.Gem|_.Directory|_.Description|
|spree_api|api|Provides REST API access|
|spree_auth|auth|Provides authentication and authorization (via authlogic and cancan gems)|
|spree_core|core|Core functionality - all other gems depend on this gem|
|spree_dash|dash|Simple overview dashboard|
|spree_promo|promo|Coupons and promotions|
|spree_sample|sample|Sample data and images|

h4. Use of Rails Engines

Each of the gems in Spree makes use of Rails Engines.  This functionality was introduced in Rails 3.0 and allows Engines to behave in a manner similar to fully-functional applications.  Relying on this mechanism provides several advantages:

h5. An Intuitive Mechanism for Customization

Default Spree functionality is provided via the Rails engine gems.  Engines can provides several aspects traditionally associated with a Rails application including (but not limited to):

* Models, views and controllers
* Routes
* Helpers
* Rake tasks
* Generators
* Locales

All of these elements can be overridden in the main Rails application.  Therefore, it is relatively simple to add Spree to your Rails application and then customize it further by supplying your own elements in that same application. A full discussion of Rails Engines is not appropriate here.  Please consult the Rails Guides for more information.

h5. Simple Distribution and Installation as Gems

Using a Spree gem is as simple as adding it to your +Gemfile+ (ie. very simple)

<shell>
  gem 'spree_core', '0.70.2'
</shell>

Distribution of Spree (and its extensions) is also consistent with Rails standards and modularity (see next.)

h5. Consistency With a Rails Standard

Prior to version 0.30.0, Spree used a complex custom mechanism for implementing "engine-like" functionality.  While it was difficult to strip this functionality out of Spree the benefits are well worth it.  Spree will now receive all of the massive testing and attention to detail that comes for free when using the Rails core.

h5. Modularity

There are differing opinions on what belongs in the "core."  People are often expressing their opinion that Spree is either "getting too fat" or "lacks basic features."  By relying on these engines (and distributing them as gems), developers are free to use only the parts of Spree that they find useful.  For instance, this would allow you to omit promotions functionality or to replace the authentication mechanism.

WARNING: The engine architecture is a work in progress.  Some of the modularity described above is theoretical and yet to be tested in a real world application.  Expect minor difficulties if you decide to use a subset of the Spree gems (although we would gladly work with you to resolve them.)

h3. Building a Sandbox Application
{'fraction_non_alphanumeric': 0.046575787082116196, 'fraction_numerical': 0.004057124310288867, 'mean_word_length': 4.436700485222762, 'pattern_counts': {'":': 20, '<': 17, '<?xml version=': 0, '>': 15, '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': '3497398', 'n_tokens_mistral': 3227, 'n_tokens_neox': 3057, 'n_words': 1837}