=begin

  $Id: README.DEV,v 1.9 2006/02/08 12:02:09 k Exp $

  Copyright (C) 2005, 2006 Toshiaki Katayama <k@bioruby.org>

= How to contribute to the BioRuby project?

There are many possible ways to contribute to the BioRuby project,
such as:

* Join the discussion on the BioRuby mailing list
* Send a bug report or write a bug fix patch
* Add and correct documentation
* Develop code for new features, etc.

All of these are welcome!  However, this document describes the last option,
how to contribute your code to the BioRuby distribution.

We would like to include your contribution as long as the scope of
your module meets the field of bioinformatics.

== License

If you would like your module to be included in the BioRuby distribution,
you need to give us right to change the license of your module to make it
compatible with other modules in BioRuby.

BioRuby was previously distributed under the GNU GPL license, but now we
are changing the license to Ruby's. 

== Coding style

You will need to follow the typical coding styles of the BioRuby modules:

=== Use the following naming conventions

* CamelCase for module and class names
* '_'-separated_lowercase for method names
* '_'-separated_lowercase for variable names
* all UPPERCASE for constants

=== Indentation must not include tabs

* Use 2 spaces for indentation.
* Don't replace spaces to tabs.

=== Comments

Don't use =begin and =end blocks for comments.  If you need to add
comments, include it in the RDoc documentation.

=== Each file must start with the following text

  #
  # = bio/db/hoge.rb - Hoge database parser
  #
  # Copyright::   Copyright (C) 2001, 2005
  #               Bio R. Hacker <brh@example.org>,
  #               Chem R. Hacker <crh@example.org>
  # License::     Ruby's
  #
  # $Id: README.DEV,v 1.9 2006/02/08 12:02:09 k Exp $
  #
  # == Blah blah blah
  #
  # See http://hoge.db/ for more details on the Hoge database.
  # ... blah blah blah ...
  #
  # == Examples
  #
  #   hoge = Bio::Hoge.new(entry)
  #   puts hoge.entry_id
  #   puts hoge.definition
  #
  # == References
  #
  # * Hoge F. et al., The Hoge database, Nucleic. Acid. Res. 123:100--123 (2030)
  #
  # * http://hoge.db/
  #

=== Documentation should be written in the RDoc format in the source code

The RDoc format is becoming the popular standard for Ruby documentation.
We are now in transition from the previously used RD format to the RDoc
format in API documentation.

Additional tutorial documentation and working examples are encouraged
with your contribution.  You may use the header part of the file for
this purpose as demonstrated in the previous section.

=== Testing code should use 'test/unit'

Unit tests should come with your modules by which you can assure what
you meant to do with each method.  The test code is useful to make
maintenance easy and ensure stability.

=== Using autoload

To quicken the initial load time we have replaced most of 'require' to 
'autoload'
since BioRuby version 0.7.  During this change, we have found
some tips:

You should not separate the same namespace into several files.

* For example, if you have separated definitions of the Bio::Foo
  class into two files (e.g. 'bio/foo.rb' and 'bio/bar.rb'), you
  need to resolve the dependencies (including the load order)
  yourself.

* If you have a defined Bio::Foo in 'bio/foo.rb' and a defined
  Bio::Foo::Bar in 'bio/foo/bar.rb' add the following line in the
  'bio/foo.rb' file:

    autoload :Bar, 'bio/foo/bar'
    
You should not put several top level namespaces in one file.

* For example, if you have Bio::A, Bio::B and Bio::C in the file
  'bio/foo.rb', you need

    autoload :A, 'bio/foo'
    autoload :B, 'bio/foo'
    autoload :C, 'bio/foo'

  to load the module automatically (instead of require 'bio/foo').
  In this case, you should put them under the new namespace like
  Bio::Foo::A, Bio::Foo::B and Bio::Foo::C in the file 'bio/foo',
  then use

    autoload :Foo, 'bio/foo'

  so autoload can be written in 1 line.

== Name space

Your module should be located under the top-level module Bio and put under
the 'bioruby/lib/bio' directory.  The class/module names and the
file names should be short and descriptive.

There are already several sub directories in 'bioruby/lib':

  bio/*.rb   -- general and widely used basic classes
  bio/appl/  -- wrapper and parser for the external applications
  bio/data/  -- basic biological data
  bio/db/    -- flatfile database entry parsers
  bio/io/    -- I/O interfaces for files, RDB, web services etc.
  bio/util/  -- utilities and algorithms for bioinformatics

If your module doesn't match any of the above, please propose
an appropriate directory name when you contribute.

== Maintenance

Finally, please maintain the code you've contributed.  The BioRuby
staff is willing to give you CVS privileges if needed.

=end

