Re: Standard libraries

On Thursday, February 12, 2004, 7:36:18 AM, Sean wrote:

> On Wednesday 11 February 2004 14:36, Dave Thomas wrote:
>> I'd like to propose two more criteria.
>>
>> 1. Nothing new gets added without complete documentation

> This is interesting.  Where, in CVS, should the non-sourcecode documentation
> go?  Are we encouraged to start making directories in ruby/doc?  For that
> matter, where's the official location for unit tests and all the extra bits
> of a project?

There's ruby/test for unit tests.  From my POV, a README or something
in stdlib directories is a good idea in some cases.

> In the short time that I've been maintaining REXML in the Ruby tree, I've
> found it rather difficult to maintain because I'm maintaining two distinct
> source trees.  It is unlikely that I'll ever use the Ruby CVS as my primary
> source repository, but it would help if I had the entire REXML tree in there
> somewhere, so that I could easily run tests.

I think you can probably put tests in there, but does that actually
solve your problem?  You keep two versions on the boil (production and
development), don't you?  Maintaining two sourcebases seems
fundamentally difficult.  What other 'bits' do you miss in the Ruby
sourcebase?

About non-sourcecode documentation in general, it should rarely be
necessary in the context of a standard library.  Documenting the main
class(es), complete with usage examples, should be enough.  If
something isn't generally useful and can't be grokked with simple
docs, what's it doing in a standard library?

Not that I'm against more and better documentation.  Like I said, a
README with some interesting text is not a bad idea.  Also, a good
online article at a stable URL (perhaps under ruby-doc.org) with a
link in the source code docs is an idea.


>> 2. For every library that gets added, another existing library should
>> be removed (using deprecation initially, but actually removed
>> eventually).

> What happens when some new functionality gets added?  IE, what do you
> deprecate when LDAP support is added to the library set?

It doesn't need to be equivalent.  There's plenty of crud in there to
support the addition of several new libraries!  ('cgi-lib', 'e2mmap',
'eregex', 'getopts', 'importenv'?, 'parsearg').  'ftools' should be
retired at some point as well.

Cheers,
Gavin