[SciPy-dev] Formal Review Process

[Pearu Peterson]

On Sat, 20 Sep 2003, Robert Kern wrote:

> A Proposal for a SciPy Module Submission Review Process
> =======================================================
> 
> :Author: Robert Kern (parts by the Boost_ group and others__)
> :Version: 0.0
> :Date: 2003-09-20
> 
> The following proposal is inspired by (and indeed partly outright lifted from)
> the `Boost Formal Review Process`_ and `Submission Process`_. It is written
> using ReStructuredText_.

Did you check out PEP-2? I think there are several things that the Boost
document does not cover: maintaining a module, for one instance.

> Rationale
> ---------
> 
> 1. The SciPy package requires a peer-review process to examine new module
>    submissions. The expertise of the CVS maintainer is limited, and the
>    number of fields for which one could write a SciPy module is large.
> 
> 2. A formal procedure for the review process makes it easier for newcomers to
>    know exactly what they have to do to get their contribution into SciPy.
>    Furthermore, a formal procedure makes it easier for Enthought to parcel out
>    the work to non-Enthought people and even to transition SciPy to a wholly
>    community-driven project if that ever becomes a goal.

Agreed.

> 3. The Boost project had a similar problem, found a solution that worked for
>    them, and wrote it up all pretty, so why not steal it? [XXX - or something to
>    this effect]

Hmm, I guess there are several projects with the same problem. Python, for
instance. I would leave this item out and mention Boost, say, in
acknowledgements (somehow so many references to Boost were annoying to me
while reading this document;-).

> Organization
> ------------
> 
> Mailing List
> ~~~~~~~~~~~~
> 
> Discussion of libraries under formal review shall take place on
> scipy-dev at scipy.org . Actual reviews of a candidate module (see section `Reviews`_) 
> during its formal review period should begin their Subject header with 
> [REVIEW - <name of module>] for the convenience of the Review Manager.
> 
> Reviewers who do not wish to subscribe to scipy-dev at scipy.org may use the GMane_
> WWW_ and Usenet_ interfaces to the mailing list. The WWW_ interface does not
> allow posting. [XXX - to be honest, I don't know if the Usenet_ one allows
> posting for this list, either.]

AFAIK, only members can post to scipy-dev mailing list.

<snip>

> The Process for a Module Submitter
> ----------------------------------
> 
> Determine Interest
> ~~~~~~~~~~~~~~~~~~
> 
> Post a message to scipy-dev at scipy.org to see if there is interest in your
> module. Describe what your module does and perhaps include a small snippet
> of code that shows how one uses it.
> 
> Preliminary Submission
> ~~~~~~~~~~~~~~~~~~~~~~
> 
> Put your (possibly unfinished) module on a website and post its location to
> scipy-dev at scipy.org . Contact the maintainers of www.scipy.org for a Zope
> account if you need web space for your module.
> 
> Submissions should follow the Code Submission Guidelines [XXX - this should
> point to something useful. For now, look at the `Code Formatting Guidelines`_
> and the `Testing Guidelines`_.]

See also PEP-7 and PEP-8.

Along the lines in PEP-2, submission should include a rather complete
documentation in order to get a better picture of the module when it will
be finished. Such a document may contain also ideas/suggestions on future
extensions of the module by proposing, say, function signatures. Such
functions are allowed to be implemented even after the module is accepted
to Scipy package.

Since Scipy should provide a solid base for scientific work, all modules
should have a mathematical background documented, most importantly,
the formal definitions of used concepts. This would allow verifying the
correctness of the results as well as avoids misusing the provided tools
by the end users who might know/use slightly different definitions for
some mathematical concepts.

> Refinement
> ~~~~~~~~~~
> 
> Discuss the module in scipy-dev at scipy.org . Fix bugs; add functionality;
> change the interface; write docs/unit tests; do whatever comes out of the
> discussion as necessary or beneficial to including the module in SciPy.
> Update the preliminary submission until it is ready for formal submission.
> 
> Submission for Review
> ~~~~~~~~~~~~~~~~~~~~~
> 
> Package your module submission in a ZIP file or gzipped tar file such that
> it can be unpacked in the scipy CVS directory [XXX - what if you need to
> patch the setup.py file or scipy_distutils files? Diff file?].

I think we can work out a setup where no modifications to setup.py files
are needed. I am thinking of adding (or using existing pre__init__.py
file) a meta file into each module directory in scipy/Lib and
scipy/sandbox that contains the following information about the module:
  - scipy level information
  - is it standalone or to be installed under scipy, etc.
  - state of the module (final,beta,...,unstable,ignore)
  - documentation
  - platform or software dependencies (setup.py would ignore the module
    when not running on the required platform or if some software is not
    installed)
  - etc.
Then setup.py will scan directories and decides whether or not to include
a module to a building/installation/distribution process based on the
content of pre__init__.py file in these directories.

Such a setup should be as simple to use as possible: adding a new module
would require two steps:
  1) unpack module to the sandbox directory
  2) create a pre__init__.py file to the module directory (unless
     submitter already had done that)

Pearu