[SciPy-dev] Technology Previews and Sphinx Docstring Annotations

[Damian Eads]

On Mon, Nov 3, 2008 at 3:39 PM,  <jh at physics.ucf.edu> wrote:
> "Damian Eads" <eads at soe.ucsc.edu> wrote:
>
>> Technology preview code is new code incorporated into the trunk of
>> SciPy ... considered production grade and well-tested ... no
>> guarantees of a stable API to enable further improvements based on
>> community feedback.
>
> Sorry, but I feel this is a poor idea.  Scipy is supposed to be
> stable.  We got rid of the sandbox for a reason.  We have too many API
> problems in scipy and even in numpy (median, FFT, and many others) to
> introduce a sanctioned mechanism for breaking APIs.
>
> If code is production-grade, *it has a stable API*.  If not, release a
> separate package, get some use experience, and let the API mature.

I don't necessarily agree. Developers have their own idiosyncrasies of
what makes a good API. I certainly have my own biases in this regard.
Developing my package on Google Code gave me the chance to iron out a
lot of API issues and fix a lot of bugs to bring the code to
stability. Discussion with other SciPy developers also helped further
refine the API. There came a point when we decided that the code was
really well-documented, mature and well-tested, and nothing further
could be done until the code was out there. One must recognize that
there are always issues when you first integrate code into a big
package that you don't think about. It's just life because you can't
anticipate everything. If you make the requirements for entry too
onerous, the larger package does not grow, and competitive edge is
lost.

As Jarrod wrote in a separate thread, I don't think it's anyone's
intention to bring back the scipy.sandbox. We're going to set the
standard very high about what is acceptable for inclusion as a
technology preview. The bar is high enough where the core SciPy
developers really can't find anything wrong with the code--it just
looks ready. Marking new code as "preview" gives us a chance to warn
the user that the code is new and a few minor changes to the API might
be made to iron things out. In most if not all cases, we're not
talking about major changes, we're talking about very minor fixes.
They are bound to occur no matter the level of maturity of the new
code so either SciPy does not grow or we give our users a heads up. I
think our users would prefer the latter.

>  If
> the code is add-on code to an existing package in scipy, your package
> can monkeypatch it into the relevant scipy package as you and
> interested others test it, or you can import it separately.  Then
> propose to bring it into SciPy as a mature package once it's ready.

Code is included in a tech preview when we think it's mature and
ready. I think that's a pretty high standard. If you set it any
higher, I don't think SciPy will grow.

>  I
> would certainly favor a section of the web site devoted to promoting
> such tests (scipy.org/nursery?  scipy.org/testbed?
> scipy.org/greenhouse?).

You are not proposing anything new here. Scikits serve as one of many
possible venues for maturing a new package. What we need is proposals
(!and the work itself!) for greatly improving the Scikit venue to
encourage more developers to use it. Developers find nothing more
emotionally unagreeable than the thought of their code collecting
dust.

> Putting a markup in the documentation is not nearly sufficient warning
> since many people exchange code (e.g., Cookbook) without reading the
> docs for all the functions and classes the code contains.  Also,
> having "Technology Demonstration" labels all over the place will only
> serve to shake people's faith in the stability of the package, and
> prevent it from ever getting a reputation for reliability.

Tech previews are common practice. QT, a popular dual-licensed GUI
package, uses the word "Technology Preview" to indicate to the user
that parts of their API are new. I would say Trolltech's employment of
this practice hasn't prevented them from building on top of their
already very strong reputation.

> Numpy and scipy should never be places for experimentation.

I don't think we're talking about that.

Damian