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

Philipp von Weitershausen philipp at weitershausen.de
Mon Mar 20 10:37:00 EST 2006


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.

The motivation and old vs. new way of doing things is covered in my
proposal. In fact, most proposals cover this. I fail to see how
proposals don't fit your above stated requirements here.

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

Maybe so. I'm saying that if they aren't, they need to be changed.
Proposals should reflect the actual change; then they're useful.

I made that point in my last email.

> and the target audience is quite different.

That doesn't mean it can't be broadened. Frankly, I think that the
current target audience and the ones I want to include in the future are
close enough and expect so much of the same information that one
documentn would be enough for both.

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

I'm not a Python core developer but I still like reading PEPs (though I
also enjoyed AMK's What's New in Python series). Hmm, I guess I
shouldn't bring myself in as an example here, though.

I just very much like the fact that when somebody asks for the big
changes in Zope 3.X, you can just say: proposal no. x, y, z and that's
it. Python can do this and so can Plone. This provides an immense amount
of transparenty.

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

Well, duh :), I would obviously convert it to the "new" procedure,
whatever that was. Otherwise my proposing the "new" procedure seems
pretty pointless.

> * 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. :)

Well, I *thought* they did what I want. I never tried to put words in
your mouth.


Let me get a final statement out that perhaps is still misunderstood or
not understood at all:

The way proposals work right now is not sufficient for what I *think*
you're trying to achieve. That's where we agree.

However, I propose to require them to be sufficient. It would not only
improve the documentation of changes (which is what I *think* your goal
is), it would also actually account for our formal development process
that we oh-so praise. Because, as you say rightfully, sometimes
proposals aren't even implemented as they were written in the first
place, or at least they weren't updated after they've been implemented
in a slightly different way. I make no exception to myself here, I
personally did this a few times (I remember at least one time with the
Message IDs as Rocks proposal). That wasn't good.

Philipp


More information about the Zope3-dev mailing list