The Well Tempered Ruby Application

Hi,

I've been starting to put together a small sample project
like GNU's
"Hello" (http://www.gnu.org
/software/hello/) that provides just the
framework of everything that a well behaved Ruby project
should
contain. The project should serve a dual role of providing a
template
for new projects and as a tutorial. I've done some cursory
searching,
but I haven't found anything.

Some of the issues that I think should be addressed in such
a sample
application.

- directory structure
- files to require in a distribution (license, readme,
samples)
- code style (tricky), version control usage
- comments, documentation, rdoc
- handling platform specific issues, native extension
- unit tests
- handling command line args, usage
- being a well behaved library
- distribution, rakefile, package format, gem, resolving
dependancies.
- version control
- register the project: rubyforge, raa, sourceforge,
anouncements here.


Does anyone know of a similar project, or would be
interested in
providing some input? Or even suggest some particularly nice
real-world projects that can be used for inspiration.

So far, I've put together the basic structure of a project
and have
started filling it with some life, mainly a longish README
and a well
documented Rakefile containing basic tasks like `rdoc` and
`package`.

Download here: http://rubyfo
rge.org/frs/?group_id=2203
or take a look at the generated docs here: http://hello.rubyforge.or
g/

I appreciate your feedback, thanks,
   -tim

Sorry for crossposting, I thought this might not only be of
interest
for ruby-doc.

Tim Becker wrote:
> Hi,
> 
> I've been starting to put together a small sample
project like GNU's
> "Hello" (http://www.gnu.org
/software/hello/) that provides just the
> framework of everything that a well behaved Ruby
project should
> contain. The project should serve a dual role of
providing a template
> for new projects and as a tutorial. I've done some
cursory searching,
> but I haven't found anything.

I believe the book Programming Ruby, AKA The Pickaxe, has
information on 
this.  There have also been some threads on ruby-talk.  I
don't recall 
much detail, but i I think certain things were vaguely
contentious.

(But these may have been the usual geek minutia items, such
as whether a 
directory should be called 'test' or 'tests'.)


I recently decided to refactor some utility code into
better-packaged 
libraries, and since I want to gem up various parts I
decided to go see 
how people structure their gem dirs.  So they might provide
a sort of 
"population sample" to examine.



> ... 
> Sorry for crossposting, I thought this might not only
be of interest
> for ruby-doc.
> 

Oh it is, since a guideline or template such as this should
encourage 
people to write docs for the code, and give them some basic
ideas for 
things such as the README  and INSTALL files, and (at least)
rudimentary 
rdoc content.

(I suspect everyone on this list also follows ruby-talk, 
but there's 
far less traffic here.)


James Britt

Tim Becker wrote:
> Hi,
> 
> I've been starting to put together a small sample
project like GNU's
> "Hello" (http://www.gnu.org
/software/hello/) that provides just the
> framework of everything that a well behaved Ruby
project should
> contain. The project should serve a dual role of
providing a template
> for new projects and as a tutorial. I've done some
cursory searching,
> but I haven't found anything.

I believe the book Programming Ruby, AKA The Pickaxe, has
information on 
this.  There have also been some threads on ruby-talk.  I
don't recall 
much detail, but i I think certain things were vaguely
contentious.

(But these may have been the usual geek minutia items, such
as whether a 
directory should be called 'test' or 'tests'.)


I recently decided to refactor some utility code into
better-packaged 
libraries, and since I want to gem up various parts I
decided to go see 
how people structure their gem dirs.  So they might provide
a sort of 
"population sample" to examine.



> ... 
> Sorry for crossposting, I thought this might not only
be of interest
> for ruby-doc.
> 

Oh it is, since a guideline or template such as this should
encourage 
people to write docs for the code, and give them some basic
ideas for 
things such as the README  and INSTALL files, and (at least)
rudimentary 
rdoc content.

(I suspect everyone on this list also follows ruby-talk, 
but there's 
far less traffic here.)


James Britt

On 9/13/06, Tim Becker <a2800276gmail.com> wrote:
> Hi,
>
> I've been starting to put together a small sample
project like GNU's
> "Hello" (http://www.gnu.org
/software/hello/) that provides just the
> framework of everything that a well behaved Ruby
project should
> contain. The project should serve a dual role of
providing a template
> for new projects and as a tutorial. I've done some
cursory searching,
> but I haven't found anything.

This looks very promising Tim. Thanks for getting started on
it. 

> [snip]
> Does anyone know of a similar project, or would be
interested in
> providing some input?

I wouldn't worry about doing anything with "coding
style", since
everyone has their own preferences.

I'd also add stuff about creating and uploading your site
to rubyforge.

Also, you may want to go to your rubyforge admin page and:

1. Shut off the following items unless/until you decide you
need them:
    * Forums
    * Tracker
    * Tasks
    * Docs
    * Surveys
    * News

2. Start a mailing list for the hello project.

> Or even suggest some particularly nice
> real-world projects that can be used for inspiration.

These should be good examples to have a look at:

* rake
* rubygems
* rmagick

---John

On 9/13/06, Tim Becker <a2800276gmail.com> wrote:
> Hi,
>
> I've been starting to put together a small sample
project like GNU's
> "Hello" (http://www.gnu.org
/software/hello/) that provides just the
> framework of everything that a well behaved Ruby
project should
> contain. The project should serve a dual role of
providing a template
> for new projects and as a tutorial. I've done some
cursory searching,
> but I haven't found anything.

This looks very promising Tim. Thanks for getting started on
it. 

> [snip]
> Does anyone know of a similar project, or would be
interested in
> providing some input?

I wouldn't worry about doing anything with "coding
style", since
everyone has their own preferences.

I'd also add stuff about creating and uploading your site
to rubyforge.

Also, you may want to go to your rubyforge admin page and:

1. Shut off the following items unless/until you decide you
need them:
    * Forums
    * Tracker
    * Tasks
    * Docs
    * Surveys
    * News

2. Start a mailing list for the hello project.

> Or even suggest some particularly nice
> real-world projects that can be used for inspiration.

These should be good examples to have a look at:

* rake
* rubygems
* rmagick

---John

On 9/13/06, Tim Becker <a2800276gmail.com> wrote:
> Hi,
>
> I've been starting to put together a small sample
project like GNU's
> "Hello" (http://www.gnu.org
/software/hello/) that provides just the
> framework of everything that a well behaved Ruby
project should
> contain. The project should serve a dual role of
providing a template
> for new projects and as a tutorial. I've done some
cursory searching,
> but I haven't found anything.

This looks very promising Tim. Thanks for getting started on
it. 

> [snip]
> Does anyone know of a similar project, or would be
interested in
> providing some input?

I wouldn't worry about doing anything with "coding
style", since
everyone has their own preferences.

I'd also add stuff about creating and uploading your site
to rubyforge.

Also, you may want to go to your rubyforge admin page and:

1. Shut off the following items unless/until you decide you
need them:
    * Forums
    * Tracker
    * Tasks
    * Docs
    * Surveys
    * News

2. Start a mailing list for the hello project.

> Or even suggest some particularly nice
> real-world projects that can be used for inspiration.

These should be good examples to have a look at:

* rake
* rubygems
* rmagick

---John

On 9/13/06, Tim Becker <a2800276gmail.com> wrote:
> Some of the issues that I think should be addressed in
such a sample
> application.

Adding a packaging script would be very helpful.  Below is
what I
whipped up for muby.. but it's imperfect.. and it's not
written in
Ruby.  I'm sure someone somewhere has something really nice
to help
with releases.

I know that Austin Ziegler has a nice packaging and
announcement
script done, but I haven't looked at it.


# TODO: learn the version number, and automatically name the
archive.
distribution_file=$(basename $(pwd))-.tar.gz

# Nuke the temporary files:
find -L ./ -name '*~' -exec rm {} \;
find -L ./ -name '.*~' -exec rm {} \;
rm -f $distribution_file
# Delete zero-length files:
# NOTE: This will delete symbolic links!
find -L ./ -name '*' -empty -exec rm {} \;

# All files, even dotfiles, but not .svn or anything in a
.svn directory.
# Ignore .fuse_hidden files created from fuse filesystems. 
This is a sign
# of a temporary file which has been locked by fuse and
shouldn't be used.
# Unfortunately, I cannot have this script's exact name in
any
sub-directory either.
tar \
--exclude "`basename $0`" \
--exclude ".svn" \
--exclude ".fuse_hidden*" \
-czvf $distribution_file * `ls -A|grep "^\."`


# BUG: This doesn't put the files in a directory.. so when
extracting
it extracts to the current
 directory!

On 9/13/06, Tim Becker <a2800276gmail.com> wrote:
> Some of the issues that I think should be addressed in
such a sample
> application.

Adding a packaging script would be very helpful.  Below is
what I
whipped up for muby.. but it's imperfect.. and it's not
written in
Ruby.  I'm sure someone somewhere has something really nice
to help
with releases.

I know that Austin Ziegler has a nice packaging and
announcement
script done, but I haven't looked at it.


# TODO: learn the version number, and automatically name the
archive.
distribution_file=$(basename $(pwd))-.tar.gz

# Nuke the temporary files:
find -L ./ -name '*~' -exec rm {} \;
find -L ./ -name '.*~' -exec rm {} \;
rm -f $distribution_file
# Delete zero-length files:
# NOTE: This will delete symbolic links!
find -L ./ -name '*' -empty -exec rm {} \;

# All files, even dotfiles, but not .svn or anything in a
.svn directory.
# Ignore .fuse_hidden files created from fuse filesystems. 
This is a sign
# of a temporary file which has been locked by fuse and
shouldn't be used.
# Unfortunately, I cannot have this script's exact name in
any
sub-directory either.
tar \
--exclude "`basename $0`" \
--exclude ".svn" \
--exclude ".fuse_hidden*" \
-czvf $distribution_file * `ls -A|grep "^\."`


# BUG: This doesn't put the files in a directory.. so when
extracting
it extracts to the current
 directory!