Re: Deprecation done right?

Gil Forcada <[email protected]> Sun, 30 Nov 2014 00:29:16 +0100
Newsgroups	gmane.comp.web.zope.plone.devel,gmane.comp.web.zope.plone.teams.framework
Message-ID	<1417303756.4302.9.camel@patam>
El dc 26 de 11 de 2014 a les 10:32 +0100, en/na Jens W. Klein va
escriure:
> 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

Hi,

just to add more options to the mix: python itself already comes with a
basic framework for deprecation warnings:
https://docs.python.org/2/library/warnings.html

And more importantly than how technically is done, how will that
information be shown to developers?

Is there going to be a static/dynamic page collecting all these
deprecations? On each release notes will be the list of deprecated
methods/modules/packages/eggs and their corresponding new locations?

And on top of that, what will be  the deprecation process? Let's say:
- on Plone 5.0 method get_foo() on package plone.original is marked as
deprecated stating that more_foo() is the new name and on plone.new
- on Plone 5.1 get_foo only imports from plone.new and calls more_foo()
(keeping the deprecation notice)
- on Plone 5.2 get_foo only gives the deprecation notice but does not
call more_foo (so plone.original is out of an official Plone release)
- on Plone 6 is completely vanished from everywhere

So a time-line on how things are deprecated and at which stages what's
done and can be expected would be extremely helpful to make that
static/dynamic page listing its status (so we can categorize a
deprecation warning within those - completely made up for the sake of an
example - levels stated above).

Everything else looks fine for me.

Cheers,
Gil

------------------------------------------------------------------------------
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

_______________________________________________
Plone-developers mailing list
Plone-developers-5NWGOfrQmneRv+LV9MX5uipxlwaOVQ5f@public.gmane.org
https://lists.sourceforge.net/lists/listinfo/plone-developers
signature.asc (application/pgp-signature, 819 B)