Re: Deprecation done right?

On 2014-11-26 10:50, Alexander Pilz wrote:
> I want to raise an idea that has helped us a lot in the past.
>
> We wanted to massively reduce the work to create releases but didn't want to refactor too much code to achieve that. In the end, we combined several packages which anyway had the same namespace into one repository. We now only release one egg which contains them all.
>
> An example for this is the Euphorie project at https://github.com/euphorie/Euphorie
>
> We release the Euphorie egg and it contains euphorie.client, euphorie.content, euphorie.deployment and euphorie.tests. When moving the github repositories, it is possible to keep the history as well.
>
> I wonder whether it would be possible to create e.g. a PloneApp egg like this.
>
> Just an idea.

In fact we discussed this way yesterday and the I liked the idea first too.

But we found one stopper:
If some addon developer uses i.e. plone.app.controlpanel as a dependency 
in its setup.py, the installation will break.

Theres more headache on supporting i.e. both 4.3 and 5.0 in an addon 
package.

I suppose a decent degreee of confusion too.

Also this approach does not help to clean up our dependency graph (or 
better call it forest) - which is another bigger problem.

Jens

> Best
> Alex
>
>> On 26 Nov 2014, at 10:32, Jens W. Klein <jens-/[email protected]> wrote:
>>
>> 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


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