[Twisted-Python] [Twisted-commits] r33889 - Merge elementresource-5395: Add renderElement, for rendering Elements.

exarkun at twistedmatrix.com exarkun at twistedmatrix.com
Sun Mar 18 09:44:08 EDT 2012


On 02:20 am, glyph at twistedmatrix.com wrote:
>
>On Mar 17, 2012, at 7:53 AM, Itamar Turner-Trauring wrote:
>>On 03/16/2012 10:51 PM, dreid at wolfwood.twistedmatrix.com wrote:
>>>Author: dreid
>>>Date: Fri Mar 16 20:51:46 2012
>>>New Revision: 33889
>>>
>>>Added:
>>>    trunk/twisted/web/topfiles/5395.feature
>>>       - copied unchanged from r33888, 
>>>/branches/elementresource-5395/twisted/web/topfiles/5395.feature
>>>Modified:
>>>    trunk/twisted/web/template.py
>>>    trunk/twisted/web/test/test_template.py
>>
>>I notice no documentation was added. Perhaps we should start requiring
>>documentation updates for all new features?
>
>Before the ticket was closed, a separate ticket was filed for 
>documentation: <http://twistedmatrix.com/trac/ticket/4983>.
>
>I don't think that adding a hard requirement for documentation on every 
>new thing as a prerequisite is necessarily a good idea (especially if a 
>new contributor wants to add a feature, this adds to an already 
>substantial burden), but someone should ask a question about 
>documentation on any ticket that doesn't explicitly account for it, 
>very early in the process.

The way I feel about documentation now makes me read this much as I 
would read a different response to a different question.

You should be able to guess the question from my imagined response:

    I don't think that adding a hard requirement for unit tests on every 
new
    thing as a prerequisite is necessarily a good idea (especially if a 
new
    contributor wants to add a feature, this adds to an already 
substantial
    burden), but someone should ask a question about unit tests on any 
ticket
    that doesn't explicitly account for them, very early in the process.

As usual, I can't prove that writing documentation at the same time (or 
before) an implementation actually produces better results, but I can 
say that this is increasingly my opinion from my personal experience.

*Even* if requiring documentation cut feature contribution by half, I 
think it'd be worthwhile.  Some number of features, undocumented, are 
worth less than half as many with good documentation.

Plus, note that it was not a new contributor who finished this 
particular ticket. ;)

Also, note that http://twistedmatrix.com/trac/wiki/ReviewProcess already 
says, as "Things your branch must contain":

    Appropriate new or modified "End User" guide documentation (in the 
form
    of Lore-formatted xhtml files in the doc/ directory)

So essentially we do require this already, but reviewers seem to largely 
ignore it (so even if we decide this should not be a requirement, 
reviewers are not doing their job properly, and that's another issue we 
should address).
Jean-Paul



More information about the Twisted-Python mailing list