[Zope3-dev] Reducing the Amount of ZCML Directives ready for review

[Martijn Faassen]

Philipp von Weitershausen wrote:
> Martijn Faassen wrote:
[snip]
> By the way, when I deprecate directives, I make the deprecation messages state
> what one should do instead of using this particular directive. Most of the
> time I print the new ZCML statement that should be used now. You should try
> running my branch on some of your software, you'll see them :).

Yes, and this is undoubtedly very useful, though it's also very terse.

>>After that, this document needs to be checked in under the
>>doc directory.
> 
> 
> I'm not sure that it is the right place. We've never so far checked any
> proposal into the doc directory, not even pretty brutal ones (e.g. the
> component architecture simplification after X3 3.0).

What happened so far shouldn't be a reason not to improve things. :)

I'm not talking about a proposal. I'm talking about a document that 
describes the changes. I'd suggest basing it on the proposal as you're 
halfway ther already.

What I'm asking for is change documentation per release, at least the 
beginnings of it, for at least the larger changes that impact end user 
code. Deprecation warnings are nice but in addition it's also nice to 
actually have a document that spells out what is going on and what you 
should be doing. It is also better for marketing as you can actually 
spell out the motivation for breaking people's code, instead of just 
presenting them with terse deprecation warnings.

I understand that pointing to the proposal helps already there, but one 
does end up in a core developer wiki and the audience for a proposal is 
different.

Regards,

Martijn