[Nitro] Contribution Guidelines

[Judson Lester]

I would have liked to see this went I got started with Og, so I'll
write what I know.  If Jo, Tom or George want to add to it, I'm not
going to say anything.

On 3/8/07, James Britt <james.britt at gmail.com> wrote:
> * How to get the current source
>   - How to get and install darcs if you don't already have it

Get darcs:
http://darcs.net/DarcsWiki/CategoryBinaries

Then:
darcs get http://repo.nitroproject.org

My quick caveat: darcs is a little testy.  Expect to occassionally
trash your local repo and start over.  Keep your repo current with
frequent pulls, and work in small, short intervals.

> * How the source code is structured

Within the repo there's three important directories: nitro, og and
raw.  There's a legacy directory called "glue" which was essentially
for common code.  There's a direction of the project to reduce and
remove the glue files, either by finding their proper place within one
of the subprojects or promote them into Tom Sawyer's Facets library,
upon with Nitro depends strongly.

> * How to run the current code without unwanted interference from
> currently installed Nitro/Og libs

The easiest way is to either set RUBYLIB, or use the -I option to
ruby.  Myself, I've got repo.nitroproject.org/og added to my RUBYLIB
in my profile.  Which is certainly an incentive to make sure it stays
reasonably stable.

> * How to write comments

The preference is for rdoc style comments, with examples and
explanation of arguments ahead of all API methods.  Honestly, anyone
looking to be helpful but less than confident about the code could do
well by writing rdoc comments.

> * Coding style

Two space indents.  No indent except for modules that the actually
classes or modules being defined in the file.  In other words:

module Nitro
class Feature
  def method(arg1, arg2)
  end
end
end

" is preferred over '

>
> * How to create a patch
> - specific commands
> - How to write change log comments

The command you'll want is "darcs record"
For most things, the short entry is enough.  You might want to use a
common prefix for related patches, as darcs does provide a feature
called "spontaneous branches" that's potentially interesting.

> * How to submit a patch

darcs send -o something.bndl
Attach the resulting bundle file to an email to the list, and George
will apply it to the main repo.

> * Current issues that are more probably deserving of attention than others

I'll leave this area mostly up to George.  I know that we're moving to
using rspec over Test::Unit, so the old test cases need to be
converted to specs, and need to be updated.  If you're considering
developing something, make sure there's a spec for it first.  If
you're up to it, writing a spec for a feature that you'd like to see
is a really good way to set it up to get written.

> James Britt

James, thanks for laying out specific questions to cue the answers.

Judson