[Zope-dev] deprecating the deprecation system?

[Hanno Schlichting]

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