[Zope3-dev] Re: Proposals vs. developer docs [was: Reducing the Amount of ZCML Directives ready for review]

[Martijn Faassen]

Philipp von Weitershausen wrote:
> Martijn Faassen wrote:
> 
>>Using proposals for communicating development-level changes is not
>>ideal. This is why Python has a separate "what changed in Python 2.x"
>>document series, which is actually readily comprehensible, as opposed to
>>many of the PEPs.
> 
> And kudos to Andrew Kuchling for writing those! I don't think anyone in the
> Zope 3 community has the time do write something like that.

It doesn't have to be as involved as it is for Python, but if we 
introduce changes that depreciate a significant amount of old usages of 
Zope 3, I think we *should* write a developer changes document. It 
should contain some explanation of what a developer is supposed to do 
instead, and perhaps a bit on why we're doing this stuff.

> Perhaps proposals aren't ideal for communicating development-level changes, but
> then again, that's what they are describing, right? Proposed development
> changes... 

They are not describing what has indeed changed, and the target audience 
is quite different.

[snip]
> As said, I'm not saying that proposals the way we have them now are sufficient.
> But, with just a little more formalization to the whole process, I think they
> could serve for what you want.

They would be helpful but they won't do what I want, just like Python's 
PEPs don't do what the typical Python developer wants when they try to 
understand what changed in a Python version and why they're getting 
deprecation warnings. They're helpful of course in case you need to know 
the little details, but PEPs are written by and for Python core 
developers, and not for Python programmers.

So, while your proposals to improve the proposal process are useful:

* it won't help with the ZCML deprecation changes (as you still used the 
old procedure)

* I don't really think your proposals target the problem I'm pointing 
out. That's fine, there are other problems to solve, after all, and 
while it's not targetting the same problem it at least improves what I'm 
pointing out somewhat too. But please stop telling me they do what I 
want. :)

Regards,

Martijn