[Zope-dev] deprecating the deprecation system?

[Martijn Faassen]

Roger Ineichen wrote:
> Hi Martijn
> 
>> Betreff: [Zope-dev] deprecating the deprecation system?
>>
>> Hi there,
>>
>> Perhaps it's time to deprecate the deprecation system.
>>
>> Why?
>>
>> * I've had good experience in the Grok project with just 
>> noting changes that might break code in the upgrade notes for 
>> Grok and telling people how to fix it. Using documentation 
>> more background can be provided and it can become a lot more 
>> clear what to do.
> 
> It is always good to have such a documentation. But what does
> this have to do with removing a deprecation system?

It's a tradeoff of burden on developers. In the Zope community we've 
sometimes assumed a bit too much a developer has infinite time to do a 
lot of required things when coding. In reality a developer has a limited 
amount of time and fiddling with the declaration system is so involved 
such a developer will declare victory. Too early, as good documentation 
won't get written.

I definitely think that something like this has happened in the past; 
people thought the deprecation system by itself was sufficient and there 
was no actual documentation with clues about what happened and what to 
do next.

>> * using the deprecation system requires quite a bit of 
>> effort, as we're adding code. Do we test deprecations? That's 
>> quite a bit of energy spent there that we could instead spend 
>> on documentation.
> 
> Yes, a deprecation system requires a lot of effort but that
> doesn't mean that the deprecation system is bad or good.
> I personaly think it's harder for me to write a good english
> documentation in the same time. But that's probably because 
> I never learned english.

So to refer to the above, I'd rather have you spent your effort on 
writing english documentation than to write deprecations of frequently 
limited utility.

>> * it's a zope-specific system no other Python projects use. 
>> Now we'll need some of them, but do we need this one?
> 
> We have many things in zope which others don't use. That's no
> mesuring base for good or bad

It's true that this cannot be the *only* argument. I'll note though that:

* we should keep Zope specific things these at a minimum if we can.

* this is not the same as, say, the use of zope.interface or 
zope.component. Those are integral to the code. The deprecation system, 
like the deferredimport system in most cases, is something that is used 
that doesn't actually do anything for the user of the package. Instead, 
it is intended to help developers. Since it's also unfamiliar to other 
Python developers, this is one more small thing that might make some 
Python developers turn away from our code.

>> * we've not been very good at removing old deprecations over time.
> 
> we can do it better

I just wonder why we *haven't* done better already!

>> * the deprecation system's messages have traditionally not 
>> been of a high quality. I recall occasions where it told me 
>> half of what to do, and certainly won't give me any 
>> background on what is going on.
> 
> a unclear message is even better then no message

That's not the comparison I want to make. An unclear message compared to 
clear documentation (that describes possible error messages you might 
get if it's more complicated than an ImportError) is the comparison I 
intend to make.

[snip]
> I'm a little bit skeptic about this proposal. And I think no reason 
> you listed does really explain why the deprecation system is bad.

The deprecation system is a system that is intended to help developers 
upgrade their code and that allows us to remove certain deprecated 
features after a while.

* we have quite a few of these developers who are not happy about the 
deprecation system.

* we've been bad at removing deprecated features after a while.

So I will conclude that from the community perspective the system hasn't 
really done its job as well as it should.

Regards,

Martijn