Philipp von Weitershausen wrote:
Martijn Faassen wrote:
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.


Zope3-dev mailing list

Reply via email to