Re: New Kwalitee Metric?

[Chris Dolan]

On Oct 24, 2006, at 9:32 AM, David Golden wrote:


I think characterizing "the basics" as being based on Module::Starter
is a little too module-specific for starters.  Do you want to also
make sure that there are files other than the boilerplate created by
all the other module skeleton modules?  What if someone puts real
tests into a boilerplate file and doesn't rename it.  And how do you
plan to address test.pl?

Moreover, I'm loath to encourage too many (more) of the "file  
exists" tests.


 $ touch t/foo.t

"Wow, my distribution has more Kwalitee, now".

The examples metric is the same:

$ touch examples/not_really_an_example

That scores the extra point.  And so what?

I'd be much more interested in seeing effort put into things like
checking if detectable prerequisites are listed in the META.yml.

Regards,
David Golden


As I've said before, Kwalitee should focus on rewarding good authors  
and catching honest mistakes, while ignoring cheaters.  If someone  
adds important tests to boilerplate.t, that's a bad practice worth  
noting.  If someone games the system and creates an empty foo.t, I'm  
content to give them a Kwalitee point they don't deserve.  Maybe  
we'll just create a Kwalitee test that detects any zero-length files  
and penalize that cheater later.


It seems easy and fairly harmless to do this:

  sub has_substantive_tests {
 return 1 if (-e 'test.pl');
 return 0 if (! -d 't');
 for my $file (File::Slurp::read_dir('t')) {
next if ($file !~ /\.t$/);
next if ($file =~ /^(?:\d+[_-]?)?load.t$/);
next if ($file =~ /^(?:\d+[_-]?)?boilerplate\.t$/);
next if ($file =~ /^(?:\d+[_-]?)?pod\.t$/);
next if ($file =~ /^(?:\d+[_-]?)?pod[_-]?coverage\.t$/);
# more boilerplate to be added later...
return 1;
 }
 return 0;
  }

That said, I'm not a Module::CPANTS developer, so I'm not going to  
dictate priorities.  The META.yml prereqs check sounds great.


Chris

--
Chris Dolan, Software Developer, Clotho Advanced Media Inc.
608-294-7900, fax 294-7025, 1435 E Main St, Madison WI 53703
vCard: http://www.chrisdolan.net/ChrisDolan.vcf

Clotho Advanced Media, Inc. - Creators of MediaLandscape Software  
(http://www.media-landscape.com/) and partners in the revolutionary  
Croquet project (http://www.opencroquet.org/)

Re: New Kwalitee Metric?

[James E Keenan]

Ovid wrote:


In short, these are the basic tests which module-starter creates 


Hey, let's remember that module-starter is not the only game in town 
when it comes to creating the structure for CPAN-ready distributions. 
See:  http://search.cpan.org/dist/ExtUtils-ModuleMaker/scripts/modulemaker


(Granted, I'm not unbiased here.)

Jim Keenan

Re: New Kwalitee Metric?

[Chris Dolan]

On Oct 24, 2006, at 9:32 AM, David Golden wrote:


I think characterizing "the basics" as being based on Module::Starter
is a little too module-specific for starters.  Do you want to also
make sure that there are files other than the boilerplate created by
all the other module skeleton modules?  What if someone puts real
tests into a boilerplate file and doesn't rename it.  And how do you
plan to address test.pl?

Moreover, I'm loath to encourage too many (more) of the "file  
exists" tests.


 $ touch t/foo.t

"Wow, my distribution has more Kwalitee, now".

The examples metric is the same:

$ touch examples/not_really_an_example

That scores the extra point.  And so what?

I'd be much more interested in seeing effort put into things like
checking if detectable prerequisites are listed in the META.yml.

Regards,
David Golden


As I've said before, Kwalitee should focus on rewarding good authors  
and catching honest mistakes, while ignoring cheaters.  If someone  
adds important tests to boilerplate.t, that's a bad practice worth  
noting.  If someone games the system and creates an empty foo.t, I'm  
content to give them a Kwalitee point they don't deserve.  Maybe  
we'll just create a Kwalitee test that detects any zero-length files  
and penalize that cheater later.


It seems easy and fairly harmless to do this:

  sub has_substantive_tests {
 return 1 if (-e 'test.pl');
 return 0 if (! -d 't');
 for my $file (File::Slurp::read_dir('t')) {
next if ($file !~ /\.t$/);
next if ($file =~ /^(?:\d+[_-]?)?load.t$/);
next if ($file =~ /^(?:\d+[_-]?)?boilerplate\.t$/);
next if ($file =~ /^(?:\d+[_-]?)?pod\.t$/);
next if ($file =~ /^(?:\d+[_-]?)?pod[_-]?coverage\.t$/);
# more boilerplate to be added later...
return 1;
 }
 return 0;
  }

That said, I'm not a Module::CPANTS developer, so I'm not going to  
dictate priorities.  The META.yml prereqs check sounds great.


Chris

--
Chris Dolan, Software Developer, Clotho Advanced Media Inc.
608-294-7900, fax 294-7025, 1435 E Main St, Madison WI 53703
vCard: http://www.chrisdolan.net/ChrisDolan.vcf

Clotho Advanced Media, Inc. - Creators of MediaLandscape Software  
(http://www.media-landscape.com/) and partners in the revolutionary  
Croquet project (http://www.opencroquet.org/)

Re: New Kwalitee Metric?

[David Golden]

On 10/24/06, Ovid <[EMAIL PROTECTED]> wrote:

now it adds boilerplate.t).  I forgot to add to the MANIFEST any of the
tests for the actual functionality :(

I it would be valuable to have a metric which checks to see if any
tests beyond the basics are included.  Of course, this could well be
impossible to check :(


I think characterizing "the basics" as being based on Module::Starter
is a little too module-specific for starters.  Do you want to also
make sure that there are files other than the boilerplate created by
all the other module skeleton modules?  What if someone puts real
tests into a boilerplate file and doesn't rename it.  And how do you
plan to address test.pl?

Moreover, I'm loath to encourage too many (more) of the "file exists" tests.

 $ touch t/foo.t

"Wow, my distribution has more Kwalitee, now".

The examples metric is the same:

$ touch examples/not_really_an_example

That scores the extra point.  And so what?

I'd be much more interested in seeing effort put into things like
checking if detectable prerequisites are listed in the META.yml.

Regards,
David Golden

New Kwalitee Metric?

[Ovid]

So I'm sitting at work and I take a look at my Class::BuildMethods
(http://search.cpan.org/dist/Class-BuildMethods/) tests and I see the
following:

 t/00-load.t
 t/pod-coverage.t
 t/pod.t

In short, these are the basic tests which module-starter creates (well,
now it adds boilerplate.t).  I forgot to add to the MANIFEST any of the
tests for the actual functionality :(

I it would be valuable to have a metric which checks to see if any
tests beyond the basics are included.  Of course, this could well be
impossible to check :(

Cheers,
Ovid

--

Buy the book -- http://www.oreilly.com/catalog/perlhks/
Perl and CGI -- http://users.easystreet.com/ovid/cgi_course/

Re: New kwalitee metric - eg/ directory

[Nick Ing-Simmons]

David Landgren <[EMAIL PROTECTED]> writes:
>Steve Peters wrote:
>> On Tue, Mar 14, 2006 at 04:52:18PM +0100, David Landgren wrote:
>
>[...]
>
>>> /eg scripts are a nice "hands-on" way of finding out how a module works 
>>> in real life.
>>>
>>> No distribution should be without one!
>>>
>> 
>> Unless, of course, it has an examples/ directory, which would cause the 
>> kwalitee test to fail. ;)  I do think its a good idea, especially with
>> large, all-encompassing type modules to provide some examples, but
>> testing for (in effect, regulating) the name of the directory that will
>> be difficult to do.
>
>Man, you wanna start a religious war or something?

I would never have tought of calling a directory eg and /e.g./ would upset VMS.
So I would have used /examples.
Except of course in Tk best candidate is called /demos with a liberal 
sprinkling 
of foo_demo in the top level ;-) 
But demos are not always the same as examples. Some Tk demos are there 
to show off run-time behaviour rather than how-to-code.

I did have the idea of looking for glob("*/examples.txt") which my guess 
is nobody has right now but could be dropped into whatever directory 
author used.


>
>I wasn't proposing to regulate anything, merely document existing 
>practices. After haved grepped through a fair portion of my local 
>mirror, at a bare minimum the pattern to match an eg directory looks like
>
>   m{/(?:e(?:xamples?|[gx])|(?:Ex|s)amples?|contrib|demo)/$}
>
>If an obvious name is overlooked, I'm sure people will draw attention to 
>it after the first iteration :)
>
>David
>
>> Steve Peters
>> [EMAIL PROTECTED]

Re: New kwalitee metric - eg/ directory

[Andrew Savige]

--- Tyler MacDonald wrote:
> Well so far the only ones I've seen are "eg", "examples", and from that
> renegade GD::Graph, "samples".

And from that eccentric Acme::Bleach, "demo".

/-\
 



 
On yahoo!7 
Avatars:  Dress up like your "Dancing with the Stars" favourites! 
http://au.avatars.yahoo.com 

Re: New kwalitee metric - eg/ directory

[Tyler MacDonald]

Tels <[EMAIL PROTECTED]> wrote:
> And packages without any actual packages, like wikimedia-graph.
> 
> But I am not sure if the agreed-on last suggestions were even implemented, 
> or anything else done: http://cpants.dev.zsi.at/ was last updated 
> 2005-12-05, e.g. over three months ago :(

AFAIK Thomas Klausner is working on getting a new improved CPANTS up
and running. He last logged into the server on Mar. 2 and put out a new
Module::CPANTS::Analyse two days ago.

Cheers,
Tyler

Re: New kwalitee metric - eg/ directory

[Tels]

Moin,

On Tuesday 14 March 2006 18:47, Tyler MacDonald wrote:
> Steve Peters <[EMAIL PROTECTED]> wrote:
> > > /eg scripts are a nice "hands-on" way of finding out how a module
> > > works in real life.
> > >
> > > No distribution should be without one!
> >
> > Unless, of course, it has an examples/ directory, which would cause
> > the kwalitee test to fail. ;)  I do think its a good idea, especially
> > with large, all-encompassing type modules to provide some examples,
> > but testing for (in effect, regulating) the name of the directory
> > that will be difficult to do.
>
>   I'm not convinced this is a good idea, but if it were implemented, I
> don't think a regexp to catch all of them would be that complicated...
> Well so far the only ones I've seen are "eg", "examples", and from that
> renegade GD::Graph, "samples".
>
>   If we were to actually use this as a metric, I'd suggest negating it
> if there is a "bin" directory, since applications may not need
> examples...

And packages without any actual packages, like wikimedia-graph.

But I am not sure if the agreed-on last suggestions were even implemented, 
or anything else done: http://cpants.dev.zsi.at/ was last updated 
2005-12-05, e.g. over three months ago :(

Best wishes,

Tels

-- 
 Signed on Tue Mar 14 21:18:49 2006 with key 0x93B84C15.
 Visit my photo gallery at http://bloodgate.com/photos/
 PGP key on http://bloodgate.com/tels.asc or per email.

 "...pornographic images stay in the brain forever." -- Mary Anne Layden;
 "That's a feature, not a bug." -- God



pgp7wyitxSB0N.pgp
Description: PGP signature

Re: New kwalitee metric - eg/ directory

[Tyler MacDonald]

Steve Peters <[EMAIL PROTECTED]> wrote:
> > /eg scripts are a nice "hands-on" way of finding out how a module works 
> > in real life.
> > 
> > No distribution should be without one!
> Unless, of course, it has an examples/ directory, which would cause the 
> kwalitee test to fail. ;)  I do think its a good idea, especially with
> large, all-encompassing type modules to provide some examples, but
> testing for (in effect, regulating) the name of the directory that will
> be difficult to do.

I'm not convinced this is a good idea, but if it were implemented, I
don't think a regexp to catch all of them would be that complicated... Well
so far the only ones I've seen are "eg", "examples", and from that renegade
GD::Graph, "samples".

If we were to actually use this as a metric, I'd suggest negating it
if there is a "bin" directory, since applications may not need examples...

Cheers,
Tyler

Re: New kwalitee metric - eg/ directory

[A. Pagaltzis]

* David Landgren <[EMAIL PROTECTED]> [2006-03-14 16:55]:
>No distribution should be without one!

Proc::Fork would definitely not benefit from an eg/ directory.

Regards,
-- 
Aristotle Pagaltzis // 

Re: New kwalitee metric - eg/ directory

[A. Pagaltzis]

* David Landgren <[EMAIL PROTECTED]> [2006-03-14 19:05]:
>Plus, the code cut and pasted from Synopses winds up with 8
>space leading indents or whatever, that you have to strip out
>and/or you forget to turn off vi's auto indenting so you have
>this massive staircase effect and the last line starts at around
>column 160. Hate hate hate.

:set paste

After pasting, use = to reindent.

Oh, and sucks to be you if you’re using another clone than vim.
:-)

Regards,
-- 
Aristotle Pagaltzis // 

Re: New kwalitee metric - eg/ directory

[chromatic]

On Tuesday 14 March 2006 10:02, David Landgren wrote:

> Plus, the code cut and pasted from Synopses winds up with 8 space
> leading indents or whatever, that you have to strip out and/or you
> forget to turn off vi's auto indenting so you have this massive
> staircase effect and the last line starts at around column 160. Hate
> hate hate.

Somebody didn't use Pod::ToDemo.

-- c

Re: New kwalitee metric - eg/ directory

[H.Merijn Brand]

On Tue, 14 Mar 2006 16:52:18 +0100, David Landgren <[EMAIL PROTECTED]> wrote:

> Hey! It's been over two months since we last had one of these suggestions!
> 
> I did battle with a module that shall remain nameless the other day. I 
> had a difficult time figuring out how to use it. In times like these, I 
> like being about to go to the build directory and p(aw|ore) through the 
> eg/ directory and take a script and bend it into a suitable shape.

or /examples or /scripts
Depending on the type of module, some can supply you with complete working
scripts (Tk, Spreadsheet::Read, XML::Twig), and some can't (DBI).

Tk installs "widget" for you, in wich you can find most of the basic
operations, whereas DBI has superb documentation that has examples and
example code scattered all through it.

So I don't think the mere existance of /eg (and some content) is worth more
qualitee.

> The package in question didn't have an eg/ directory, so I had to spend 
> far more time studying the source and running it through the debugger 
> than I really cared to.
> 
> For instance, I know that when I have something tricky to do with
> HTML::Parser, I know there's always going to be something close to what 
> I need to do in the eg/ directory. I think its a good adjunct to POD, 
> which tends to be more (or should be) more theoretical.
> 
> /eg scripts are a nice "hands-on" way of finding out how a module works 
> in real life.
> 
> No distribution should be without one!

/me mumbles Acme

-- 
H.Merijn BrandAmsterdam Perl Mongers (http://amsterdam.pm.org/)
using & porting perl 5.6.2, 5.8.x, 5.9.x  on HP-UX 10.20, 11.00, 11.11,
& 11.23, SuSE 10.0, AIX 4.3 & 5.2, and Cygwin.   http://qa.perl.org
http://mirrors.develooper.com/hpux/   http://www.test-smoke.org
   http://www.goldmark.org/jeff/stupid-disclaimers/

Re: New kwalitee metric - eg/ directory

[David Landgren]

Tels wrote:

Moin,


My modules are usually so feature crammed that they need a few examples 
for showing what you can all do with it or to enable the user oto use the 
modul without having to write/use perl code first.


Plus, the code cut and pasted from Synopses winds up with 8 space 
leading indents or whatever, that you have to strip out and/or you 
forget to turn off vi's auto indenting so you have this massive 
staircase effect and the last line starts at around column 160. Hate 
hate hate.


David


Best wishes,

Tels



--
"It's overkill of course, but you can never have too much overkill."

Re: New kwalitee metric - eg/ directory

[Nicholas Clark]

On Tue, Mar 14, 2006 at 12:48:52PM -0500, David Golden wrote:
> Adam Kennedy wrote:
> >For all those component distributions I consider it a failure if it is 
> >so complex that you need something more than just three or four lines 
> >from the SYNOPSIS.
> 
> Maybe there should be a Kwalitee metric for the length of the synopsis?

I was thinking this too. Some synopses aren't.

Nicholas Clark

Re: New kwalitee metric - eg/ directory

[David Landgren]

Steve Peters wrote:

On Tue, Mar 14, 2006 at 04:52:18PM +0100, David Landgren wrote:


[...]

/eg scripts are a nice "hands-on" way of finding out how a module works 
in real life.


No distribution should be without one!



Unless, of course, it has an examples/ directory, which would cause the 
kwalitee test to fail. ;)  I do think its a good idea, especially with

large, all-encompassing type modules to provide some examples, but
testing for (in effect, regulating) the name of the directory that will
be difficult to do.


Man, you wanna start a religious war or something?

I wasn't proposing to regulate anything, merely document existing 
practices. After haved grepped through a fair portion of my local 
mirror, at a bare minimum the pattern to match an eg directory looks like


  m{/(?:e(?:xamples?|[gx])|(?:Ex|s)amples?|contrib|demo)/$}

If an obvious name is overlooked, I'm sure people will draw attention to 
it after the first iteration :)


David


Steve Peters
[EMAIL PROTECTED]



--
"It's overkill of course, but you can never have too much overkill."

Re: New kwalitee metric - eg/ directory

[David Golden]

Adam Kennedy wrote:
For all those component distributions I consider it a failure if it is 
so complex that you need something more than just three or four lines 
from the SYNOPSIS.


Maybe there should be a Kwalitee metric for the length of the synopsis?

:-)

Regards,
David Golden

Re: New kwalitee metric - eg/ directory

[Tels]

Moin,

David Landgren wrote:
> Hey! It's been over two months since we last had one of these
> suggestions!
>
> I did battle with a module that shall remain nameless the other day.
> I had a difficult time figuring out how to use it. In times like
> these, I like being about to go to the build directory and p(aw|ore)
> through the eg/ directory and take a script and bend it into a

Whats the /eg directory you speak of? :D

On Tuesday 14 March 2006 18:13, Adam Kennedy wrote:

[snip]
> I have a shitload of distributions, mostly small components.
>
> For all those component distributions I consider it a failure if it is
> so complex that you need something more than just three or four lines
> from the SYNOPSIS.

> How about we penalise anything with a eg/example directory, for not
> having clear enough documentation, or a clean enough design/API. :)

> There's a lot of reasons for not having an eg/ directory, unless your
> distribution is huge and complicated, like say bioperl.

You are contradicting yourself :)

My modules are usually so feature crammed that they need a few examples 
for showing what you can all do with it or to enable the user oto use the 
modul without having to write/use perl code first.

Best wishes,

Tels

-- 
 Signed on Tue Mar 14 18:40:44 2006 with key 0x93B84C15.
 Visit my photo gallery at http://bloodgate.com/photos/
 PGP key on http://bloodgate.com/tels.asc or per email.

 Ich bin mit der Gesamtsituation unzufrieden!



pgpaN87I3Gp1Q.pgp
Description: PGP signature

Re: New kwalitee metric - eg/ directory

[Adam Kennedy]

David Landgren wrote:

Hey! It's been over two months since we last had one of these suggestions!

I did battle with a module that shall remain nameless the other day. I 
had a difficult time figuring out how to use it. In times like these, I 
like being about to go to the build directory and p(aw|ore) through the 
eg/ directory and take a script and bend it into a suitable shape.


The package in question didn't have an eg/ directory, so I had to spend 
far more time studying the source and running it through the debugger 
than I really cared to.


For instance, I know that when I have something tricky to do with
HTML::Parser, I know there's always going to be something close to what 
I need to do in the eg/ directory. I think its a good adjunct to POD, 
which tends to be more (or should be) more theoretical.


/eg scripts are a nice "hands-on" way of finding out how a module works 
in real life.


No distribution should be without one!


I have a shitload of distributions, mostly small components.

For all those component distributions I consider it a failure if it is 
so complex that you need something more than just three or four lines 
from the SYNOPSIS.


How about we penalise anything with a eg/example directory, for not 
having clear enough documentation, or a clean enough design/API. :)


There's a lot of reasons for not having an eg/ directory, unless your 
distribution is huge and complicated, like say bioperl.


Adam K

Re: New kwalitee metric - eg/ directory

[Steve Peters]

On Tue, Mar 14, 2006 at 04:52:18PM +0100, David Landgren wrote:
> Hey! It's been over two months since we last had one of these suggestions!
> 
> I did battle with a module that shall remain nameless the other day. I 
> had a difficult time figuring out how to use it. In times like these, I 
> like being about to go to the build directory and p(aw|ore) through the 
> eg/ directory and take a script and bend it into a suitable shape.
> 
> The package in question didn't have an eg/ directory, so I had to spend 
> far more time studying the source and running it through the debugger 
> than I really cared to.
> 
> For instance, I know that when I have something tricky to do with
> HTML::Parser, I know there's always going to be something close to what 
> I need to do in the eg/ directory. I think its a good adjunct to POD, 
> which tends to be more (or should be) more theoretical.
> 
> /eg scripts are a nice "hands-on" way of finding out how a module works 
> in real life.
> 
> No distribution should be without one!
> 

Unless, of course, it has an examples/ directory, which would cause the 
kwalitee test to fail. ;)  I do think its a good idea, especially with
large, all-encompassing type modules to provide some examples, but
testing for (in effect, regulating) the name of the directory that will
be difficult to do.

Steve Peters
[EMAIL PROTECTED]


signature.asc
Description: Digital signature

New kwalitee metric - eg/ directory

[David Landgren]

Hey! It's been over two months since we last had one of these suggestions!

I did battle with a module that shall remain nameless the other day. I 
had a difficult time figuring out how to use it. In times like these, I 
like being about to go to the build directory and p(aw|ore) through the 
eg/ directory and take a script and bend it into a suitable shape.


The package in question didn't have an eg/ directory, so I had to spend 
far more time studying the source and running it through the debugger 
than I really cared to.


For instance, I know that when I have something tricky to do with
HTML::Parser, I know there's always going to be something close to what 
I need to do in the eg/ directory. I think its a good adjunct to POD, 
which tends to be more (or should be) more theoretical.


/eg scripts are a nice "hands-on" way of finding out how a module works 
in real life.


No distribution should be without one!

David
--
"It's overkill of course, but you can never have too much overkill."