[Twisted-Python] Specifications

[glyph at divmod.com]

On 04:34 pm, exarkun at divmod.com wrote:
>On Sun, 12 Aug 2007 15:09:38 -0000, glyph at divmod.com wrote:
>>On 02:27 am, jml at mumak.net wrote:

>Personally, I don't want discussion features for the things for which I 
>have
>been using specification wiki pages.  I can have discussions with 
>people in
>meatspace or on IRC.  I want the *outcome* of a discussion on the page.

I can see the value of that.  What I'm referring to is the synergy 
between, for example, the wikipedia "talk" page and the main entry page. 
There's value in discussion, and there's value in viewing only the 
outcome so as not to be confused by the discussion.  Trac has a nod to 
this in that tickets have both a description and a comments section; the 
problem with this being the aforementioned lack of versioning on the 
comments section.

In other words the fact that we even need to have this discussion is 
entirely a problem with the tools in question, not a problem with the 
idea of specifications.  Specifications are *great*.  I wish we had 
specifications for everything.  Tickets (at least for small things) 
should ideally always contain or refer to a full specification of what 
is being done and why.
>Chris and I have been using wiki pages for this primarily as a shared 
>work
>space to hash out ideas.  None of the topics we've approached has 
>actually
>been implemented yet, so I'm not really sure what the next phase of 
>this
>looks like.  However, I would expect that once there is some agreement 
>about
>a particular specification, whatever necessary tickets will be created 
>and
>they will live out the normal ticket life cycle.  Whether the 
>specification
>wiki pages live on past the implementation task isn't something I've 
>thought
>a lot about.  Of the top of my head, I don't see any reason for them 
>to, but
>I also can't think of too many compelling reasons to delete them, 
>either.

I don't have any problem with this, either.  Any kind of web-space is 
appropriate for this kind of forming-ideas planning, and the Twisted 
wiki particularly so, for Twisted features.

Once the specification is relatively fixed (and maybe the process of 
fixing a specification so that is "officially" agreed upon needs some 
discussion) then just having a link in the ticket's description to the 
wikiword of its specification would also be pretty good.

The thing I'm concerned about is that once we start having reports of 
open specifications, statuses for them, owners, assignees, and so on, 
it's going to be a parallel tracker with separate priorities and 
workflow.  I don't even object to *that* in principle, it might make 
sense on a project with more resources (more "management overhead" in 
particular).  I just can't see us coping with it now.

Sorry if this all seems overly wordy, I just want to make sure it's 
clear how narrow the scope of my objection is :).  I don't want to 
discourage anyone from planning, specifying, writing down things about 
Twisted in any format they so choose - but I am concerned about that 
process creating more work.
>To respond to one of jml's points, though, here is a list of the
>specifications which currently exist:
>
>  http://twistedmatrix.com/trac/wiki/TitleIndex
>
>Just search for "Specification" ;)

And in closing, I don't object to this informal mechanism either :).