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

Jim Fulton jim at zope.com
Sat Aug 25 13:01:08 EDT 2007

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.

- 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.


Jim Fulton			mailto:jim at zope.com		Python Powered!
CTO 				(540) 361-1714			http://www.python.org
Zope Corporation	http://www.zope.com		http://www.zope.org

More information about the Zope3-dev mailing list