On Thu, Sep 16, 2004 at 12:38:52AM -0400, Gavin Sinclair wrote:
> A long time ago, we had a spirited discussion about categorisation of
> gems. I'm now suggesting that for 0.9 we implement a simple category
> feature, taken more or less directly from RPA. Even just marking gems as
s/RPA/rpa-base/ (yes I really have to rename it :)
> being a library or an application would be a start. Using an existing
> ontology of keywords would also be a good idea.
Well the code is there, but the ontology is yet to be created...
I'm not sure it does what you want though: it handles hierarchical
classification, not a keyword-based one, and it is self-validating in
the sense that unknown classifications are rejected.
Some sources of inspiration:
http://raa.ruby-lang.org/cat.rhtml?category_major=Libraryhttp://raa.ruby-lang.org/cat.rhtml?category_major=Application
In general, the categorization in RAA is horrible :-( Redundant
categories, mixture of general & specific: for instance, all of
Net, WWW, TCP-IP, Chat... are top-level...
http://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/makefile-categories.htmlhttp://www.freebsd.org/ports/http://packages.debian.org/stable/http://cpan.org/modules/by-category
In the past you ("the RubyGems team") have expressed your concerns about
classifications being too rigid, etc. I believe that the hierarchical
classification should be managed carefully (look at RAA...), but you
can give quite a lot of free room for developers by:
* allowing multiple categorization
* providing a keyword-based system in a addition to the hierarchical approach.
You'd have to find a way to encourage reuse of existent keywords,
while making it possible to introduce new ones.
> Speaking of summary and description, there's confusion in the community
> (OK, in my head) about how best to use these fields.
These are some of the informal rules I'm following for the descriptions
in RPA:
* first line should contain a brief synopsis. Better not repeat the
name, e.g. "Simple templating library" is better than "Foo is a simple
templating library."
* a longer description follows after a blank line. This must contain
enough information to be able to decide whether it's worth installing
or not, but shouldn't provide usage info, etc.
* my descriptions tend to be formatted in a RDoc-ish style
I'd refer you to
http://www.debian.org/doc/debian-policy/ch-binary.html#s-descriptions
for more precise guidelines. In general, there's quite a lot to be learned from
the Debian Policy Manual, so you could as well read most of it and also
some parts of the FreeBSD Porter's Handbook
http://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/
All in all, this is what a typical description looks like (some fields removed)
name: rake
version: 0.4.7-1
classification: Top.Application.Devel
description: A simple ruby build program with capabilities similar to make
Rake has the following features:
* Rakefiles (rake's version of Makefiles) are completely defined in
standard Ruby syntax. No XML files to edit. No quirky Makefile
syntax to worry about (is that a tab or a space?)
* Users can specify tasks with prerequisites.
* Rake supports rule patterns to sythesize implicit tasks.
* Rake is lightweight. It can be distributed with other projects as a
single file. Projects that depend upon rake do not require that rake
be installed on target systems.
> I'm tempted to
> advise people to give a brief summary (they already do) and this:
>> spec.description = File.read('README')
Ouch better not IMHO, the README normally contains *far* more information
than needed, and its format is not appropriate for the description in general.
> Some agreement on this would be good, leading to some documentation, and
> ensuring that the implementation is good, regarding formatting, etc.
And you also have to find ways to encourage good practices without
hindering the freedom of those who really know what they are doing. This
is pretty hard...
--
Running Debian GNU/Linux Sid (unstable)
batsman dot geo at yahoo dot com