[Twisted-Python] "Stability: Unstable" might be clearer as "API

[glyph at divmod.com]

On Sun, 24 Sep 2006 22:46:20 -0400, Paul Swartz <paulswartz at gmail.com> wrote:
>On 9/24/06, Andrew Bennetts <andrew-twisted at puzzling.org> wrote:
>>As a tangent, people seem to get confused by this.  Perhaps it would be 
>>less
>>ambiguous to replace "Stability: Unstable" with something like:
>>
>>     API status: in flux

>I heartily second "in flux".  I've gotten lots of e-mail from
>t.w.p.oscar users asking what "unstable" means.

I suspect that the phrase "in flux" may be equally jargonesque, although it does make more sense to me personally.

There are 3 problems here though:

 1. Modules' stability markers are not kept up-to-date as community perception changes.

Not much that we can do about that except have periodic docstring reviews.

 2. The terminology doesn't immediately make much sense.

Changing the terminology in the way that Andrew suggests could probably improve this situation, but I think that it would not be a complete solution to the problem, because:

 3. There's no good description of what we mean by the specialized terms we have chosen to describe a module's status.

I think that means we need to update this document:

    http://twistedmatrix.com/projects/core/documentation/howto/faq.html#auto5

regardless of any change (or no change) to the terminology.