On 02:20 am, gl...@twistedmatrix.com wrote:
>
>On Mar 17, 2012, at 7:53 AM, Itamar Turner-Trauring wrote:
>>On 03/16/2012 10:51 PM, dr...@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
_______________________________________________
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
