[Zope3-dev] RFC: Guide for maintaining software in the Zope repository

[Philipp von Weitershausen]

On 25 Aug 2007, at 19:01 , Jim Fulton wrote:

> On Aug 23, 2007, at 8:37 PM, Philipp von Weitershausen wrote:
>
>> We have 100+ packages that make up what used to be distributed as  
>> "Zope3". We have numerous more packages in svn.zope.org. Most of  
>> them are developed, released and distributed individually. We like  
>> to think this is a good thing (I certainly do). But currently we  
>> have a bit of a chaos [2]. It's not bad, but I fear without some  
>> guidance, it'll get worse.
>>
>> Christian Theune recently wrote a document [1] in which he  
>> outlined how we should get to a development process and what  
>> topics it should touch.  This document is very hands-on and  
>> describes actions that should be taken to reach these goals. I've  
>> taken the liberty to jump ahead and write down some current  
>> practices:
>>
>> http://svn.zope.org/*checkout*/Sandbox/philikon/foundation/ 
>> maintaining-software.txt
>
> This is a great start. Thanks!
>
> A few small points:
>
> - I'm going to mostly stay out of the style debate except to note  
> that the Zope style guide builds on PEP8.  It doesn't disagree with  
> it much accept in the case of some naming, due to the fact that the  
> ZSG made a commitment before PEP8 did.

It seems to me that we should certainly reference the ZSG in the  
guide. Contrary to previous comments, I do believe that the ZSG could  
use some cleanup and could be made more concise. Since the  
differences mostly seem to revolve around method and function naming,  
I'm almost inclined to leave it open to the package authors whether  
to choose camelCase (ZSG) or under_score (PEP8) naming, as long as  
it's consistent within a pacakge.

> - On doctest, there should be greater emphasis on there being 2  
> kinds of tests, executable documentation and other tests.  I think  
> there is value in executable documentation, but it should be  
> documentation first.  A lot of our doctests that we think/wish are  
> documentation are not very good documentation.  We need to do a  
> better job of this.
>
> I do feel strongly that even non-documentation tests should be  
> written in a fairly literate way with documentation of the test  
> itself,  I strongly prefer the doctest format for these tests, but  
> I don't want to be an evil dictator about it. I suggest that  
> classic unit tests can be used for new tests, but *only* if they  
> are well documented.  I've never seen a classic unit test that was,  
> but I'm open to the theoretical possibility. :)
> BTW, I've seen poorly documented doctests too.

Thanks for the feedback. I've improved the "Automated tests" section  
accordingly. Could you check it again and see if I captured your  
comments right?