Codebase Guidelines

The BioCatalogue codebase is:

• hosted on Rubyforge
• licensed under the BSD license
• uses Subversion (SVN) (repository)
• runs on Rails 2.3.2 and Ruby 1.8.5 / 1.8.6

• In the Rails application, NEVER commit the following to the repository (svn:ignore properties should ensure that this doesn't happen, but be vigilant!)
  • anything in
    • /log/
    • /tmp/
    • /var/
  • /config/database.yml (see below)
  • /config/initializers/biocat_local.rb (see below)
  • /config/initializers/geokit_local.rb (see below)
  • /config/initializers/mail.rb (see below)
  • /db/schema.db (this is automatically generated by Rails)
  • any temporarily generated files in /public/
  • /vendor/plugins/acts_as_solr/solr/solr/data (and it's contents)
  • Anything in /vendor/plugins/acts_as_solr/solr/temp

• Set ENABLE_SEARCH to false temporarily for the initial db:migrate used to set up the database in the first place

See installation instructions page

• When editing code, set your indent length to 2 spaces for best results when viewing code.

• rake

• mongrel (only required if running script/server)

• solr-ruby

• addressable

• dnsruby

• plugin_test_helper
  • Only required to test certain plugins.

• tzinfo (used by Rails 2.2.2)

• daemons.
  • gem install daemons
  • Used mainly for the background processing runner.

• SystemTimer
  • gem install SystemTimer
  • To have proper timeouts (see: http://ph7spot.com/articles/system_timer).

• RubyInline
  • gem install RubyInline
  • The memcache-client gem takes advantage of this gem to provide greater performance.

• libxml-ruby
  • gem install libxml-ruby

• memcache-client
  • Although this is embedded in the codebase it still needs to be installed in order to prevent the version within Rails (v1.6.4.99) to be loaded instead.

• json
  • gem install json

• mysql
  • gem install mysql

• rubaidh-google_analytics

• jnunemaker-twitter

• oauth

• mash

• httparty

• crack

• ruby-hmac

• onyx-cache-money

• memcache-client
  • Although Rails has it's own version of memcache-client, this one is so much faster.

• soap4r
  • Used to create rpc driver to soap services
  • IMPORTANT: make sure you do not have the httpclient gem installed locally as this will cause the application to break!

• disqus
  • For disqus integration

• geokit

• rpx_now
  • NOTE: this has been modified to provide proxy support (in lib/rpx_now.rb from around line 162)

• seer

• version_info

None

• railsbench, ONLY if you want to benchmark the Rails app.
  • [sudo] gem install skaes-railsbench (NOTE: you first need http://gems.github.com in your gems repo list)

• nkallen-cache-money

• BioRuby. The project is also available on github
  • gem install bio

• state_machine (used by some plugins)
  • gem install state_machine

• wysihat-engine
  • For rich text editor

• acts_as_activity_logged from myExperiment

• acts_as_bookmarkable

• acts_as_solr -
  • Was: acts_as_solr from myExperiment codebase
  • Then: http://github.com/bcardarella/acts_as_solr/tree/master
  • Now: http://github.com/mattmatt/acts_as_solr/tree/master

• acts_as_trashable

• addthis
  • For the bookmarking widget

• after_commit
  • Patched by Jits on 2009-06-22 to include logging on failure (ref: http://github.com/ericworking/after_commit/commit/66aa170e302f04694a7312ee389164a64649ae60).

• annotations

• asset_packager (with YUI compressor support)
  • Article - http://railsillustrated.com/more-speed-improvements-with-asset_packager.html
  • GitHub - http://github.com/eandrejko/asset_packager/tree/master

• atom_feed_helper

• auto_complete

• better_logging

• country_and_region_select

• exception_notification - [Super] Exception Notifier Plugin for Rails

• geokit-rails

• headliner

• markaby

• rails-widgets

• recaptcha

• redbox

• request_profiler

• rounded_corners_helper

• slugalizer

• template_inliner
  • Note, the entire call to render inlined partial must be on the one line for template inliner to work.

• validates_email_veracity_of

• validates_existence

• validates_url_format_of

• white_list

• will_paginate

• service_deployments = instances of a service hosted AND provisioned in a location by a provider
• All the following refer to the actual service type object (eg: SoapService or RestService etc):

service_version_instance
service_instance 
service_versionified
service_versionified_instance

• For SOAP we assume the service structure is all from wsdl doc (ie: provider) whereas REST we assume the service structure is all from the submitter.

• Tagging the SoapService object itself is not relevant, only tagging either the root (Service) or SoapOperation/Inputs/Outputs. Although, we now have cases where tags have been added to the SoapService object itself.

See: Pseudo-Synonyms for Search

See: Background Processing

See: Caching

We use a plugin called asset_packager to combine and compress the CSS and JS files to greatly improve the client side loading environment.

This plugin, in production mode, automatically generates two files:

• /public/javascripts/base_packaged.js
• /public/stylesheets/base_packaged.css

… which are the combined and compressed versions.

This plugin relies on the YUI Compressor and thus requires a JVM environment to run in.

IMPORTANT: when doing at update to the servers, the following command MUST be run in order to refresh the packaged JS and CSS files:

rake asset:packager:build_all  

Any major new features/development should be done in branches instead of trunk to ensure that trunk is always relatively stable. When development in the branch has reached a stable point then it can be merged back into trunk and deployed to the site. This way we can do updates to the beta site in a more managed fashion and make sure we get bug fixes into trunk asap.

For information on branching/merging in SVN:

• From the SVN book (must read) - http://svnbook.red-bean.com/en/1.1/ch04.html
• Command line examples - http://research.mosuma.com/faq/howto/svn_branch_merge
• Step by step - http://blog.evanweaver.com/articles/2007/08/15/svn-branching-best-practices-in-practice/
  • Note: this suggests switching your local copy to the branch, which is quicker, but it is highly recommended to keep your local copy of trunk and instead checkout a fresh copy of each branch that you need to work on. This way you can work on trunk if you need to make any bugfixes etc.

Important:

• All branches must be placed in /branches
• Be careful about the configuration of database.yml for your branches - if the branch you will be working on requires major db schema changes then you might want to consider not reusing the db used for your trunk working copy (since if you have to then switch back to trunk to fix something you will be connecting to a db that is potentially inconsistent with trunk). Instead, create a new db for that branch and import the content from the existing db.

The recommended procedure:

• Identify a discrete piece of work and create a branch in /branches for it (e.g.: /branches/read-users-minds).
• Checkout your branch locally (ie: creating a new local copy of that branch).
• Set up configuration etc as mentioned earlier in this page.
• Write some code!
• When you are happy that your branch is stable enough, to be merge the changeset into a local working copy of trunk. NOTE: at this stage, nothing has changed in trunk in the repository, just your local copy, so don't worry about conflicts etc.
• Resolve any conflicts and fix any arising bugs.
• Commit the changes you have made to trunk. In your commit message, make sure you explain which branch you have merged into trunk and from what revision (eg: if I created my branch in revision 2450 and then merged all changes from then till now into trunk I would say so in the commit message).
• Pray to your divine saviour*

* Non-religious people are probably screwed here.

You can use either the svn command line tools or Eclipse (with the Subclipse plugin installed). Eclipse/Subclipse provides excellent merging and conflict resolution tools. For detailed instructions on how to merge back the changes in a branch to trunk check out: http://blog.daemon.com.au/go/blog-post/merging-with-subversion-and-eclipse.

• Look to using background-solr instead of acts_as_solr.

• You see the error undefined constant XXXX::YYYYY -

Check if you have the file:

./<APPL_ROOT>/config/initializers/biocat_local.rb 

If not then copy:

./<APPL_ROOT>/config/initializers/biocat_local.rb.pre 
    into 
./<APPL_ROOT>/config/initializers/biocat_local.rb

• Instructions on how to integrate bundler into a rails 2.3.x application are available on the [http://gembundler.com/rails23.html| bundler page]
• See the [http://gembundler.com/man/bundle-install.1.html| bundler man pages] for details on bundler commands
• Bundler requires a recent version of rubygems, so update your rubygems first with :

 gem update --system 

• Now install the bundler gem

 sudo gem install bundler 

• Then from the application root

 bundle install --path path/to/where/gems/should/be/installed

If no path option is specified, bundler will install gems to your system default gems location