Please note: This page is a work in progress.

Codebase Guidelines

The BioCatalogue codebase is:


  • 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



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


Need to be installed on server / development environment

  • rake
  • mongrel (only required if running script/server)
  • tzinfo (used by Rails 2.2.2)
    • gem install daemons
    • Used mainly for the background processing runner.
    • gem install RubyInline
    • The memcache-client gem takes advantage of this gem to provide greater performance.
    • 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

Embedded within codebase (no need to install)

    • Although Rails has it's own version of memcache-client, this one is so much faster.
    • 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!
    • For disqus integration
    • NOTE: this has been modified to provide proxy support (in lib/rpx_now.rb from around line 162)

Need to be installed only for development purposes


For future (do not install just yet)

  • railsbench, ONLY if you want to benchmark the Rails app.
  • BioRuby. The project is also available on github
    • gem install bio

Plugins (already in /vendor/plugins/)

Important Design Decisions

  • 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):
  • 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.

Background Processing


See: Caching

Asset Packager (for CSS and JS)

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  

Developing in Branches

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:


  • 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:


Problems/Errors and Possible Solutions

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

Check if you have the file:


If not then copy:


Using Bundler

 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

development/codebase_guidelines.txt · Last modified: 2011/02/04 13:23 by jits Creative Commons License Valid CSS Driven by DokuWiki do yourself a favour and use a real browser - get firefox!! Recent changes RSS feed Valid XHTML 1.0