[Zope3-dev] Zope 3 as a reliable platform?!?

[Martin Aspeli]

Martijn Faassen wrote:
> 
> So, my proposal for Zope 3.4:
> 
> * have a developer_notes file or directory somewhere.
> 
> * let this contain the developer-visible changes.
> 
> * it should be focused on how to change your code. That's the important 
> bit. Motivations and such might also be useful to have there, but the 
> main thing should be: this change from so and so to so and so, so to 
> make this work, do the following.
> 

+10 - this is becoming really important to us Plone people, since we have
some code that needs 2.8 compatability, and some that will probably be 2.10
or 2.11 going forward. People see examples in the 2.8-compatible code and
try to follow them, and then end up doing silly things. Even those of us who
are pretty close to the core get confused sometimes.

Here's the kind of thing I'd love to see, in a clear, well-structured
document:

"""
<subscriber> ZCML directive -- The 'factory' attribute has been renamed
'handlers' because (whatever good reason??). Instead, you should now do
<subscriber handler=".module.method" for=".interfaces.ISomeEvent" />
"""

The important things are (a) it's easy to find this by skimming through a
document (oh, I'm pretty sure I'm using a <subscriber> somewhere); (b) there
is some rationale. This makes the change easier to remember than just having
a blind rule to follow, and allows us to scrutinise changes more; (c) there
is a clear example of how it should be done - examples may not speak more
than 1,000 words but they're good for 500 at least.

This type of document would need to be written by someone who understands
the changes, and probably by one or two people not a dozen. A CHANGELOG is
mostly useless because it contains too much detail and not enough context.
It's fine as an audit trail, but it's very hard to put changes in the
context of your own code if they're structured cronoligically and limited to
a few key words on a line or two.

If anything, this may make me bug philiKON a bit less on IRC ... :-)

Martin
-- 
View this message in context: http://www.nabble.com/Zope-3-as-a-reliable-platform-%21--tf2207550.html#a6133275
Sent from the Zope3 - dev forum at Nabble.com.