Deprecation done right?

In yesterdays framework-team hangout we discussed briefly the best way 
to deprecate single functions, classes, methods, modules or whole python 
eggs.

Background:
===========

At the moment we have way to many single packages. This is a nightmare 
for our release manager.

So we planned to merge core functionality like the controlpanels into 
Products.CMFPlone. Another example and low hanging fruit is the merge of 
plone.behavior into plone.dexterity. And more is planned. But thats not 
the question here - please discuss in a separate thread ;)

Moving stuff around in core results always a headache for addon 
developers and integrators. Good deprecation acts as a pain killer. So 
we plan to not break existing imports.

To have a clear communication about deprecations and in order to avoid 
different (confusing) styles of deprecation, we need a deprecation 
guideline.


Proposal:
=========

Case A: Deprecation because of renaming
---------------------------------------

We may want to rename methods, or functions in order to get a more 
consistent api or because of a typo, etc.
We never just rename, we always provide a deprecated version 
logging/raising a verbose deprecation warning with information where to 
import from in future.

We need a wrapper/decorator which handles this. (To be defined)

Case B: Moving a module, class, function, etc to another place
--------------------------------------------------------------

For some reason, i.e. merging packages or resolving cirular import 
problems, we need to move things around.

The object is imported at the old place, but logs/raises a verbose 
DeprecationWarning telling with information where to import from in future.

(details to be defined)


Case C: Deprecation of a package
--------------------------------

A whole package (folder with __init__.py)

- all imports still works, but they are raising Deprecation Warnings

- ZCML still exists, but is empty (or includes the zcml from the new 
place if theres no auto import (i.e. for meta.zcml). Not sure if we can 
raise/log deprecation warnings in this case

(details to be defined)


Case D: Deprecation of a whole python egg
-----------------------------------------

We will provide a last major release with no 'real' code, only backward 
compatible (bbb) imports are provided, case C applies.

The README clearly states why it was moved and where to find the code now.


Question to you
===============

Please comment the above proposal. Did we miss a case? Something is odd?

Is there already some package around dealing with this cases?

We know there are:

zope.deprecation
     looks like what we need.
     but seems not raising any warning here, is this still useful? Did I
     miss something?

zope.deferredimport.deprecated
     helps if code moves around

Is there something for zcml as well?

thanks in advance for your ideas

Jens
-- 
Klein & Partner KG, member of BlueDynamics Alliance


------------------------------------------------------------------------------
Download BIRT iHub F-Type - The Free Enterprise-Grade BIRT Server
from Actuate! Instantly Supercharge Your Business Reports and Dashboards
with Interactivity, Sharing, Native Excel Exports, App Integration & more
Get technology previously reserved for billion-dollar corporations, FREE
http://pubads.g.doubleclick.net/gampad/clk?id=157005751&iu=/4140/ostg.clktrk