-*- outline -*-

* Intro

We were wondering how we should go about keeping track of the
consensuses (sp?) we reached on the perlunit-devel mailing list.
Matthew was all for a cumbersome set of tags so we could grep the list
for "points".  Christian suggested a simple text file in CVS which we
modify as appropriate.  This is a compromise - a simple text file
marked up for use with emacs' "outline-mode".  Most of the active
developers use emacs.

Issues currently being discussed on the list can be kept track of here
by listing any suggestions made or conclusions which were reached.
Once it's decided what needs to be done, the details should be moved
to doc/TODO and someone will get on with implementing them.

Please only update this file on the main branch!

** Links back to the mailing list

Might be handy for those with local archives, but dropping message-ids
in this file will make a mess IMHO  -- mca

* Coding conventions

If in doubt, conform to the style shown in the existing code.

** use vs. require

After a discussion on perlunit-devel in March 2001, subject 'Towards
sensible failure messages', we settled on use rather than require, except
where we only want to load a module if we need it, of course.

** whitespace

No hard tabs, 4 column indent level.  

* Auto-adding tests, Test::Unit::TestSuite->new()

** interaction with inheritance

Broken in v0.13, it will take SUPER::test_foo if test_foo is
an inheritted method in the class being scanned.

Fixed by Piers.

** regexps to pull functions called /^test/

I think current consensus is to change the default to /^test[_A-Z]/
but make it configurable.

I seem to have lost that thread -- mca

* Debug methods

Not much agreement yet, here are some of the suggestions

** $self->debug()

A dead/unused patch from Matthew, the idea was a default debug in the
base T:U:TestCase class and methods to override it. Messy and
inconvenient.

** $self->listener->debug($@)

Some say listeners are Java-ish. Others say that they're good anyway.
9-)

Arguments are headed towards something like
       debug( level => 123,
	      user => "simple message",
	      developer => "complicated message" );
or some variation on the theme.

This all looks rather verbose so far though. 8-(

** clever things with caller()

one vote for [MCA] (provided you can override it)
one vote against? [PDC]

* Documentation

** Where?

Where should it be kept? At the moment it lives almost entirely in POD
and mailing list/message board format, and so is inaccessible.

A pod2html pass of released software should probably be served on the
website.

Matthew's (almost finished) cvspublish.pl script could do most of this
but is probably overkill. Also it doesn't grok MANIFEST files.

There is a documentation manager on SF. The front door is not too
friendly and there is no back door to the data inside it.

** API & PerlUnit overview

Current favourite is to point at the JUnit docs.

There is in 'src/api' a set of basic perl modules containing the
essence of the structure, but they're getting old.

Also, the SF message boards have some knowledge which needs
distilling.

* Namespace pollution

** classes used during self-tests

We're going to try to avoid it while generating "inner classes" or
whatever, for the self-tests.

** keys in the TestCase object hash  [not yet discussed]

T:U::TestCase::new is biting into namespace belonging to classes
inherited from T:U::TestCase .. currently it only takes _name ... I'm
wondering whether we should go to '__' prefix in the C tradition for
"magic things", since the perlunit user shouldn't need to mess with
this? -- mca

Not sure I understand what you're getting at here. The PITA approach would be
to name all the keys used only by T:U::TestCase as 

'Test::Unit::TestCase::keyname', which is a pain to work with, but probably
the best practice. See the discussion in Damian Conway's Object Oriented Perl. 

   -- pdc

* TODO lists

Moved to doc/TODO.

* Packaging

[mca: Christian has SourceForge and CPAN packaging pretty much wrapped
up *cough*, this is documented in another file in this directory]

** Debian GNU/Linux

[mca: Since I use perlunit for production work, I'm tempted to roll a
package if it's not too tricky. There is a stack of reading to do
first though (I'm not an official Debian developer)

Relevant bit from /usr/doc/dh-make-perl/README

  dh-make-perl will create the files required to build
  a debian source package out of a perl package.
  This works for most simple packages and is also useful
  for getting started with packaging perl modules.

  There is an override mechanism in place to handle most of
  the little changes that may be needed for some modules
  (this hasn't been tested much, though).

  Using this program is no excuse for not reading the
  debian developer documentation, including the policy,
  the perl policy, the packaging manual and so on.

See also http://www.uk.debian.org/devel/  ]

** RedHat

[mca: I made a RH package a long time ago... don't remember how]