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. * 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. * 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've not been very good at removing old deprecations over time. * 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. * for moving code around we have an alternative system: a backwards compatibility import, documentation about what to do, and a tool part of the test runner which can point out indirect imports. I therefore propose we do the following: * look at any package which uses deprecation warnings now. * rip out the deprecation warnings and backwards compatibility code. Even if it's really expiring in 2010 (I doubt we have much of this). When you do so and you think anyone might still using that code path, please make a remark in zope3docs/source/migration/34to35.rst about what's going on and what people are to do. * run the compattests to see whether anything breaks. I think it's quite possible some deprecated code is in use by the Zope libraries themselves. :) Thoughts? Regards, Martijn
On Thu, Mar 5, 2009 at 17:35, Martijn Faassen <faassen@startifact.com> wrote:
* 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.
True, but Grok-users will, thanks to it's new pre-1.0 status be more prepared for changes. Just an observation... I don't really have an opinion on the actual question. But I will talk out loud here: I think the goal, allowing third-party modules to support at least two versions of the framework at once, where commendable, but it may very well be that the work this caused was more than what it would be have been to support several versions by conditional imports etc in the third-party modules. On the other hand, if you have say, Zope 3.4 depends on zope.foobar 3.4.x, and you in zope.foobar 3.5.0 make a BBB-breaking refactoring without deprecation, and you then in 3.5.1 introduce a new, unrelated feature, it means you can't use that new feature in Grok while Grok still depends on Zope 3.4, which is a shame. But maybe not a problem. Deprecating would allow you to do that. It's probably an impossible task to have both backwards compatibility and still have innovation without loads of old cruft in the code. It becomes a balancing act. I don't know where to put that balance. Maybe we could have deprecation but for much shorter time. Say, between releases of the framework? Or we could simply not deprecate, but encourage backwards compatibilities, at least until a new major version is released of the framework? -- Lennart Regebro: Pythonista, Barista, Notsotrista. http://regebro.wordpress.com/ +33 661 58 14 64
Martijn Faassen wrote:
Perhaps it's time to deprecate the deprecation system.
From my personal view, I think the deprecation system works in certain cases in its current form. It does not work as the only means of documenting API changes for the evolution of software.
I tend to think of software life cycles in the same way as most other processes work over time. Based on some status quo you get a rather predictable and slow-paced change rate for some time. We capture these in maintenance releases or minor feature releases. At a certain point the amount of innovation that has happened or the amount of dissatisfaction with the status quo gets too much and people urge for major change and revolution. We call those new major versions. The move from a 1.0 to 2.0 release, introducing major backwards incompatible changes. For Plone, we have adjusted our release strategy to match this model. Over two years there's a stable and predictable release series currently named 3.x. But people want major change and leave some of the baggage of the past. We call this the next major version numbered 4.0. The version numbers in the Zope community don't follow those normal practices of a 1.0, 2.0 and so forth scheme for known historical reasons. It's nevertheless the same cycle that happens.
From a Zope2 perspective we have seen Five integration, major innovation and rapid change in Zope 2.7 and 2.8. It cooled down again and Zope 2.9 to 2.11 have only seen minor and predictable changes. Zope 2.12 tries to make major changes again. For Zope3 after the X3 release we had a period of still rapid changes for some time, but 3.2 up to 3.4 have been quite conservative. Now people want to change more things again at a more rapid speed without caring about byte-sized deprecation.
I'd say that the deprecation system in its current form is well suited and has worked for the more silent times. It is not suited for covering the changes of a major new version. One of the problems with those major new versions is that often not only code constructs, import locations or the like change. We develop new approaches or best practices which need documentation in terms of real text explaining them including examples to show them. For Plone 4 we decided to not use the deprecation system on the level of import locations, but rather focus on writing articles and text documenting the changes. Once such a new major version is out, the deprecation system will be usable again and can cover the more slow paced evolution that will follow. It's a good tool, but not appropriate for the task at hand. Hanno
Hanno Schlichting wrote: [snip interesting analysis]
I'd say that the deprecation system in its current form is well suited and has worked for the more silent times. It is not suited for covering the changes of a major new version.
I'm not sure it has worked so well. I've seen code in zope.* packages refer to deprecated code in other zope.* packages for a very very long time. I'd also say that we run into the deprecation system *more* in the wild times, such as when Jim refactored the local component registration system. Is a wholesale moving of a class to another place part of the wild times or the quiet times? I'd argue it's more part of the wild times, as a class is rarely moved by itself - the motivation behind this is to more logically arrange the code in packages, and this is something that will touch more than one package. [snip]
Once such a new major version is out, the deprecation system will be usable again and can cover the more slow paced evolution that will follow. It's a good tool, but not appropriate for the task at hand.
Given the history of its usage in Zope 3 I have my doubts, but perhaps Plone's experience is different and a model we could follow. Regards, Martijn
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?
* 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.
* 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
* we've not been very good at removing old deprecations over time.
we can do it better
* 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
* for moving code around we have an alternative system: a backwards compatibility import, documentation about what to do, and a tool part of the test runner which can point out indirect imports.
I therefore propose we do the following:
* look at any package which uses deprecation warnings now.
* rip out the deprecation warnings and backwards compatibility code. Even if it's really expiring in 2010 (I doubt we have much of this). When you do so and you think anyone might still using that code path, please make a remark in zope3docs/source/migration/34to35.rst about what's going on and what people are to do.
* run the compattests to see whether anything breaks. I think it's quite possible some deprecated code is in use by the Zope libraries themselves. :)
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 only reason to use a deprecation system is to ensure that there is a deprecation period. I think the (real) reason why we can't use a deprecation system is that we don't like to support a deprecation period anymore because we like to evolve our package in a incompatible way now and not later. This makes our deprecation system useless and a migration path document is the only solution to handle that. Any other reason not using a deprecation system is just based on to less available time to support it or lazyness. btw, Right now it's very unclear how we identify versions like 3.4 / 3.5 What does that mean since packages have it's own versions e.g. 3.7.5 and are release within 3.4. How do you identify the zope version (3.4/3.5) of such a package?
Thoughts?
+/- 0 I let me surprise, let's try something new. We can still fallback to a deprecation system if everything else fails. Regards Roger Ineichen
Regards,
Martijn
_______________________________________________ Zope-Dev maillist - Zope-Dev@zope.org http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )
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
Martijn Faassen wrote:
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.
The system certainly hasn't worked as well as we had hoped. Nonetheless issuing deprecation warnings is not an invention of Zope but Python does this itself. The deprecation warnings you get from Python are most of the times not more than: "X is gonna go away, use Y instead". But you will then go to the upgrade guide or documentation section of the new Python version and look at the new features. Having the focus more on human readable documentation is certainly a good idea. Hanno
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Martijn Faassen wrote:
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.
* 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.
* 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've not been very good at removing old deprecations over time.
* 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.
* for moving code around we have an alternative system: a backwards compatibility import, documentation about what to do, and a tool part of the test runner which can point out indirect imports.
I therefore propose we do the following:
* look at any package which uses deprecation warnings now.
* rip out the deprecation warnings and backwards compatibility code. Even if it's really expiring in 2010 (I doubt we have much of this). When you do so and you think anyone might still using that code path, please make a remark in zope3docs/source/migration/34to35.rst about what's going on and what people are to do.
* run the compattests to see whether anything breaks. I think it's quite possible some deprecated code is in use by the Zope libraries themselves. :)
Thoughts?
I'm already on record as favoring this strategy. ;) Tres. - -- =================================================================== Tres Seaver +1 540-429-0999 tseaver@palladion.com Palladion Software "Excellence by Design" http://palladion.com -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.6 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iD8DBQFJsIuF+gerLs4ltQ4RAinsAKCOPGiU+IOTHNlbry4fyRK7/eF+UQCcDXPp EiBufuv8s02yz4wk2oLljpw= =9juK -----END PGP SIGNATURE-----
Martijn Faassen wrote:
Thoughts?
+ sys.maxint to all of that from me :-) I think documenting that something is going to go away is useful, but ultimately, people only really worry about it when something stops working. I've got way to bored to the millions of meaningless deprecation warnings emitted by *released* zope/plone/blah versions over the years... Chris
Chris Withers wrote:
I think documenting that something is going to go away is useful, but ultimately, people only really worry about it when something stops working.
I think it's not that simple. Look at the amount of work people put into the Zope stack in recent month to get rid of DeprecationWarnings for the sha, md5 or sets modules or various other warnings emitted by Python 2.6. There's lots of energy spent on those warnings *before* they break anything.
I've got way to bored to the millions of meaningless deprecation warnings emitted by *released* zope/plone/blah versions over the years...
Yes, me too. But I feel our use of the system wasn't very good. I have seen people putting in deprecation warnings for things they didn't like, but without there being an alternative. At other times we deprecated particular single methods of something to move them some place else without much clear win. To me it seems that we get warnings from the Python level on a somewhat broader level, like: the entire package X is going away, use Y now. The message itself is short and concise, but you can look up detailed documentation about the new package and its API. There must be something to learn from that. Hanno
Hi Chris
Betreff: Re: [Zope-dev] deprecating the deprecation system?
Martijn Faassen wrote:
Thoughts?
+ sys.maxint to all of that from me :-)
I think documenting that something is going to go away is useful, but ultimately, people only really worry about it when something stops working.
I've got way to bored to the millions of meaningless deprecation warnings emitted by *released* zope/plone/blah versions over the years...
Millions, that doesn't sound like serious statement. Can you give an example of a meaningless deprecation warning? I don't know of any useless deprecation message. Every message makes me faster if I update my or zope code. Could it be that you depend on packages for a long time which deprecated code and don't have time to update them? I allways update my projects and migrate them if I work on something. This way I don't see any deprecation message on my production system. Or if so, I know what I have to for a next release. Regards Roger Ineichen
Chris
_______________________________________________ Zope-Dev maillist - Zope-Dev@zope.org http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )
Roger Ineichen wrote at 2009-3-8 14:38 +0100:
... Can you give an example of a meaningless deprecation warning?
A few of the deprecations I have disliked for a long time:
/home/dieter/Z/Products/Archetypes/__init__.py:15: DeprecationWarning: The module, 'Products.CMFCore.CMFCorePermissions' is a deprecated compatiblity alias for 'Products.CMFCore.permissions'; please use the new module instead. from Products.CMFCore import CMFCorePermissions
Why should I bother about deprecations in foreign packages (Archetypes in the case above)?
/home/dieter/Z/Base/lib/python/Products/CMFCore/utils.py:667: DeprecationWarning: format_stx() will be removed in CMF 1.6. Please use StructuredText.StructuredText.HTML instead.
Why should the short "format_stx" no longer be supported and instead the monster "StructuredText.StructuredText.HTML" be used? And here is my favorite:
/home/dieter/Z/Products/HaufePortalBase/__init__.py:86: DeprecationWarning: The product_name parameter of ToolInit is deprecated and will be ignored in CMF1.6: HaufePortalBase
The "product_name" parameter used to be mandatory -- thus all calls to "ToolInit" had to use it. Then, a means was found to derive it automatically from the context. The developper was so happy that he wanted all others immediately drop the parameter -- result: several dozens of deprecation warnings for each start -- in trivial cases, where the automatically derived information was identical to the explicitly provided.... I called out "what a stupidity".... -- Dieter
On Mon, Mar 9, 2009 at 15:56, Dieter Maurer <dieter@handshake.de> wrote:
The "product_name" parameter used to be mandatory -- thus all calls to "ToolInit" had to use it. Then, a means was found to derive it automatically from the context. The developper was so happy that he wanted all others immediately drop the parameter -- result: several dozens of deprecation warnings for each start -- in trivial cases, where the automatically derived information was identical to the explicitly provided.... I called out "what a stupidity"....
I agree that this deprecation warning is pointless. The parameter can just stay there and be ignored, no need to warn. But the description of the change is incorrect, the decision to ignore the parameter was for reason, not just because we could, even if I don't exactly remember what the reason was now. :) -- Lennart Regebro: Pythonista, Barista, Notsotrista. http://regebro.wordpress.com/ +33 661 58 14 64
Lennart Regebro wrote at 2009-3-9 17:09 +0100:
On Mon, Mar 9, 2009 at 15:56, Dieter Maurer <dieter@handshake.de> wrote:
The "product_name" parameter used to be mandatory -- thus all calls to "ToolInit" had to use it. Then, a means was found to derive it automatically from the context. The developper was so happy that he wanted all others immediately drop the parameter -- result: several dozens of deprecation warnings for each start -- in trivial cases, where the automatically derived information was identical to the explicitly provided.... I called out "what a stupidity"....
I agree that this deprecation warning is pointless. The parameter can just stay there and be ignored, no need to warn. But the description of the change is incorrect, the decision to ignore the parameter was for reason, not just because we could, even if I don't exactly remember what the reason was now. :)
The parameter was pointless in the first place. One and only one value for it worked -- the one that could be determined automatically. Thus, it was good to get rid of it -- just the deprecation warning was silly: instead, a value different from the only correct one should have resulted in an exception. -- Dieter
On Wed, Mar 11, 2009 at 19:55, Dieter Maurer <dieter@handshake.de> wrote:
The parameter was pointless in the first place. One and only one value for it worked -- the one that could be determined automatically.
Which is why it was removed. :) (and also, I think there was a use case where the one calling the parameter *didn't* know the value. Five I think. Ah well)
Thus, it was good to get rid of it -- just the deprecation warning was silly: instead, a value different from the only correct one should have resulted in an exception.
True. -- Lennart Regebro: Pythonista, Barista, Notsotrista. http://regebro.wordpress.com/ +33 661 58 14 64
participants (7)
-
Chris Withers -
Dieter Maurer -
Hanno Schlichting -
Lennart Regebro -
Martijn Faassen -
Roger Ineichen -
Tres Seaver