From: Intransition <transfire@...>
Date: 2011-06-15T21:33:53+09:00
Subject: Re: Plugin best practices



On Jun 15, 7:37 am, Josh Cheek <josh.ch...@gmail.com> wrote:
> On Wed, Jun 15, 2011 at 4:36 AM, Intransition <transf...@gmail.com> wrote:
> > If your making a plugin/extension for another project, do you create a
> > hyphenated lib file or do you put the library file in a subdirectory,
> > e.g. say it's a plugin for rdoc,
>
> >    lib/rdoc-foo.rb
>
> > Or
>
> >    lib/rdoc/foo.rb
>
> According to both of the resources I'd reference, it should be the latter.
>
> =====  http://guides.rubygems.org/patterns/#use_dashes_for_extensions =====
>
> Adding new functionality to an existing gem? Use a dash. Some examples
> include net-http-persistent and autotest-growl. Usually this implies that
> you’ll have to require into their directory tree as well. For example, `gem
> install net-http-persistent` becomes `require 'net/http/persistent'`.
>
> =====  http://chneukirchen.github.com/rps/ =====
>
> Project names SHOULD only contain underscores as separators in their
> names. If a project is an enhancement, plugin, extension, etc. for some
> other project it SHOULD contain a dash in the name between the original name
> and the project’s name. File names and directory structure SHOULD correspond
> like this:
>
>     Library: foo-bar
>     Directory: lib/foo/bar
>     Namespace: Foo::Bar
>
>     Library: foo_bar
>     Directory: lib/foo_bar
>     Namespace: FooBar

Yea, I was afraid you would say that ;-)

Technically speaking this is a bad idea. The reason is that if someone
wanted to install a project in the traditional site ruby locations
(e.g. via setup.rb), then there is the potential for file name
conflicts such that the last package installed will clobber the file
from a previous package. It also can be a problem with RubyGems where
two files can have identical paths in the eyes of #require, in which
case the file that gets loaded is simply first come first serve.
Obviously in practice it's a rare issue b/c of the low odds that two
programmers will use the same file name, and even less likely that
both offending packages will get installed on the same system. But the
potential exists. In fact, with regards to plugins/extensions, the
most common pattern I've seen are rdoc's and rubygem's use of an
identical file in all project's, none of which could work in a site
install, and are only made possible by installation via RubyGems, by
scanning the GEM_PATH.

I would highly recommend following YARD's pattern of `yard-foo`
instead, if possible (it might not always be possible b/c of the
design of the program being extended.)