[Zope-dev] Deprecate ITerms in zope.app.form? [Re: zope.browser?]

[Tres Seaver]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Martijn Faassen wrote:

<snip platform / KGS stuff>

For the case of *library* packges, rather than platforms, forcing users
into lockstep on dependencies is less desirable.

Example
- --------

Assume that developer Fred releases a given library distribution,
'foo-1.2.tar.gz', with the following dependency in its setup.py::

  install_requires=['bar >= 0.9']

And inside the 'foo' package, some module does the following import::

  from bar.baz import someAPI

At the time this version of foo is released, the following versions of
'bar' are available from Barney's website:

  bar-0.9.tar.gz
  bar 1.0.tar.gz
  bar-1.0.1.tar.gz

None of those 'bar' versions have a deprecation for the import above,
and so code which uses the 'foo' package emits no warnings.

At some point, Barney decides to refactor the 'bar' package, and moves
'someAPI' from the 'baz' module to a new 'qux' module.  If nothing else
in 'baz' *uses* 'someAPI', Barney has two choices:

- - Import the symbol for BBB, and leave it "forever"::

  from bar.qux import someAPI   # BBB

- - Import it for BBB, but mark it deprecated::

  import zope.deprecation # note new dependency!
  zope.deprecation.deprecated('someAPI',
    'Usually a multi-line explanation here')
  from bar.qux import soemAPI   # BBB

The issue is moot if the 'baz' module actually uses the moved symbol.
Nobody actually puts deprecation warnings around non-BBB imports created
during refactorings if the module doing the import actually uses the symbol.

Note that Barney is *adding* cruft to 'baz' (the several lines of stuff
to this module to spell the deprection), and that he has created a
future maintenance burden (ripping out the import / deprecation at some
point in the future).

Then look what happens to Wilma's application which uses 'foo', and
transitively depend on 'bar':  once she updates to bar 1.1 (e.g., to
pick up an unrelated bugfix), her application begins to emit warning
messages, even though the application doesn't use the deprecated symbol
directly.  Either Wilma must live with the warning, or else she leans on
Fred to release a new version of 'foo'.

Note that the relased version of 'foo' continues to *work* with baz >=
1.1 (at least until the eventual removal).  Assume that 'foo' is
hyper-stable, and would otherwise not need to be updated at all;  Fred
is now in the position of being pressured to make a gratuitous release
in order mollify Wilma.

If Fred *does* want to accomodate the complaints from the application
author, he then has to make choices:

- - Support both locations via a conditional import (AKA add cruft)::

  try:
      from baz.qux import someAPI
  except ImportError:
      from baz.bam import someAPI

- - Drop support for the older location, and update the 'install_requires'
  accordingly.  Now, users who pick up the new 'foo' version will be
  forced to upgrade 'bar', even if they would otherwise not want the
  new version.


>> Most of my components work with a wide version range of other
>> components. I would not like to expose a single version.
>> Usually, I include a narrative of the form: known to work with 2.6.x
>> through 2.11.x; may work with other versions as well (not tested).
> 
> What will you do once Zope 2 is split up into multiple packages? How
> would you express such a thing about Zope 3 if there is no canonical
> list of versions (such as KGS)? Grok is in the position of Zope 2 or
> Zope 3 here.
> 
> Of course we prefer the individual components that Grok is composed
> of, and extensions to Grok, to work with multiple versions of Grok.
> That's unrelated to the need to actually *have* versions of Grok in
> the first place. It's desirable to have each component work with a
> range of versions of other components. It's also desirable to make a
> collection of components work out of the box with a well-known set of
> versions that can be communicated about, because this selection itself
> has a version number as well.
> 
>> In the past, I have seen excessive deprecation warnings and had
>> the feeling that the warning feature is overused (as many new features).
> 
> I think it's clear that many people do not like seeing deprecation
> warnings during startup and runtime and that it's been quite a burden
> on developers. I can see how it is frustrating to developers (one or
> multiple steps away)/
> 
> It's also clear to me that if we want Zope 3 to move forward, we need
> a much less convoluted dependency structure and have the ability to do
> some relatively bold refactoring. We will therefore need to move
> things around a lot more, and I fully intend to make progress on that,
> and join Roger in his work.
> 
> I therefore propose we make a new kind of deprecation system that uses
> the same system to mark up source code as we have now, but does never
> emit the warnings during run-time. Instead we create an external
> scanning tool that can report about deprecated imports in a package
> (and perhaps help fix them automatically).

I think the idea that we need to prod downstream developers to update
their packages in accordance with our refactorings is suspect,
especially given that both we and they have to add cruft (ours to emit
the warning, theirs to suppress it).  Note that all this effort / cruft
is to support a hypothetical "futurue cleanliness", which only
materializes when we remove our cruft and break BBB.

I'm calling that win hypothetical because the warning-emitting cruft
often stays in the codebase for *years*, even long after the promised
removal date.  Back when we were releasing a monolithic Zope3, there was
at least some effort before those releases to go chase down the IOUs in
the code and do the rmovals.  Now that individual packages are
separately released, the "maybe-ness" of the future removal is even more
problematic, as the exploded, deprecation-emitting package may never
even get a new release.

If we that there is a real goal other than "future cleanliness" for the
deprecation system, then a system which requries warnings to be
explicitly enabled (e.g., via a tool, or an environment variable, or
something) would help reduce the burden on the downstream developer.


Tres.
- --
===================================================================
Tres Seaver          +1 540-429-0999          tseaver at 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

iD8DBQFJTMbc+gerLs4ltQ4RAhZrAKCOdJk2keNyzAaKuNU1tMASCSRaIACffAuK
jXpk6uehghc4Iv1azVitzKs=
=0WfK
-----END PGP SIGNATURE-----