<commit_before>h2. Developer Tips and Tricks

This guide presents accumulated wisdom from person-years of Spree use.


endprologue.

h3. Upgrade Considerations

h4. The important commands

+rake spree:upgrade+ 
will copy in any new "infrastructure" files, e.g. new configuration or javascript or 
style files. It saves you from needing to run the +spree+ command to get an empty project and then copying
changes across.

NOTE. currently this over-writes existing files, so be careful if you have experimental changes. (IDEA: use +-b+ flag on the copies? it does help)


h4. Dos and Don'ts

NOTE. Try to avoid modifying +config/boot.rb+ and +config/environment.rb+: use "initializers":#initializers instead.

h4. Tracking changes for over-ridden code

Be aware that core changes might have an impact on the components you have over-ridden in your project. 
You might need to patch your local copies, or ensure that such copies interact correctly with changed
code (e.g. using appropriate ids in Html to allow the javascript to work).

If you can help us to generalise the core code so that your preferred effect is achieved by altering 
a few parameters, then this is more useful than duplicating several files. Ideas and suggestions always
welcome.  

INFO. The "Spree Wiki":/wiki/scripts contains a few scripts to automate some of the checking.


h4. Initializers

Initializers are run during startup, and are the recommended way to execute certain settings. You can 
put initializers in extensions, thus have a way to execute extension-specific configurations.

See the "extensions guide":extensions.html#extension-initializers for more information. 


h3. Debugging techniques

h4. Use tests!

Use +rake spec+ to test basic functioning after you've made changes.


h4. Analysing crashes on a non-local machine

If you're testing on a server, whether in production or development mode, the following code in one
of your +FOO_extension.rb+ files might save some time. It triggers local behaviour for users who have
an admin role. One useful consequence is that uncaught exceptions will show the detailed error page
instead of +404.html+, so you don't have to hunt through the server logs. 

<shell>
Spree::BaseController.class_eval do
  def local_request?
    ENV["RAILS_ENV] != "production" || current_user.present? && current_user.has_role?(:admin)
  end
end
</shell>

h3. Managing large projects

h4. To fork or not to fork...

Suppose there's a few details of Spree that you want to over-ride due to personal or client preference, 
but which aren't the usual things that you'd over-ride (like views) - so something like tweaks to the
models or controllers. <commit_msg>Added tip on using a Compass watcher to detect SASS changes<commit_after>h2. Developer Tips and Tricks

This guide presents accumulated wisdom from person-years of Spree use.


endprologue.

h3. Upgrade Considerations

h4. The important commands

+rake spree:upgrade+ 
will copy in any new "infrastructure" files, e.g. new configuration or javascript or 
style files. It saves you from needing to run the +spree+ command to get an empty project and then copying
changes across.

NOTE. currently this over-writes existing files, so be careful if you have experimental changes. (IDEA: use +-b+ flag on the copies? it does help)


h4. Dos and Don'ts

NOTE. Try to avoid modifying +config/boot.rb+ and +config/environment.rb+: use "initializers":#initializers instead.

h4. Tracking changes for over-ridden code

Be aware that core changes might have an impact on the components you have over-ridden in your project. 
You might need to patch your local copies, or ensure that such copies interact correctly with changed
code (e.g. using appropriate ids in Html to allow the javascript to work).

If you can help us to generalise the core code so that your preferred effect is achieved by altering 
a few parameters, then this is more useful than duplicating several files. Ideas and suggestions always
welcome.  

INFO. The "Spree Wiki":/wiki/scripts contains a few scripts to automate some of the checking.


h4. Initializers

Initializers are run during startup, and are the recommended way to execute certain settings. You can 
put initializers in extensions, thus have a way to execute extension-specific configurations.

See the "extensions guide":extensions.html#extension-initializers for more information. 

h3. Debugging techniques

h4. Use tests!

Use +rake spec+ and +rake test+ to test basic functioning after you've made changes.


h4. Analysing crashes on a non-local machine

If you're testing on a server, whether in production or development mode, the following code in one
of your +FOO_extension.rb+ files might save some time. It triggers local behaviour for users who have
an admin role. One useful consequence is that uncaught exceptions will show the detailed error page
instead of +404.html+, so you don't have to hunt through the server logs. 

<shell>
Spree::BaseController.class_eval do
  def local_request?
    ENV["RAILS_ENV] != "production" || current_user.present? && current_user.has_role?(:admin)
  end
end
</shell>

h4. Editing stylesheets - Compass and SASS

To avoid having to restart the web server to see changes to SASS stylesheets, use
a compass watcher:

<shell>
compass --watch --sass-dir path/to/sass --css-dir ./path/to/compiled
</shell>

The compass watcher will compile any changed files and write them to the css-dir.

When editing my site extension's sass, I use these paths, if you use the gem spree boot mode
it may be different for you:

<shell>
compass --watch --sass-dir vendor/extensions/site/public/stylesheets/sass --css-dir ./public/stylesheets/compiled
</shell>

h3. Managing large projects

h4. To fork or not to fork...

Suppose there's a few details of Spree that you want to over-ride due to personal or client preference, 
but which aren't the usual things that you'd over-ride (like views) - so something like tweaks to the
models or controllers. 
{'fraction_non_alphanumeric': 0.05802675585284281, 'fraction_numerical': 0.004849498327759197, 'mean_word_length': 4.251097453906936, 'pattern_counts': {'":': 6, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5508586', 'n_tokens_mistral': 1668, 'n_tokens_neox': 1583, 'n_words': 865}