Re: deprecation policy

[Mikael Hermansson <mikeh bahnhof se>]

Hmm looks my last mail doesn't come to the list (Balsa crashed :-/

>     - immediately remove widgets from API docs

Don't forget to remove example applications for deprecated widgets
because I think new users is looking on those examples
when writing they're first Gtk app...


Greats

MH.

Den Fri, 06 Oct 2000 05:29:20 skrev Havoc Pennington:
> 
> Hi,
> 
> I think we should have a documented policy for how deprecation works.
> To get discussion going, here is an initial proposal. I'm not going to
> defend it too strongly if people have good comments, because I just
> thought about it in the last hour or so. ;-)
> 
> There are several categories of deprecation I can think of:
> 
>  a) code is badly broken, we don't have resources to fix it due 
>     to the extent of the breakage.
>     (GtkTree, GtkText)
>  b) code is useless bloat not of general interest
>     (GtkGammaCurve)
>  c) code is replaced by a better alternative which new code should 
>     use
>     (GtkCList)
> 
> I would handle these as follows.
> 
> a) This is the embarassing category. First we commit to never have
>    this happen again; no more patches will be accepted that introduce
>    nonworking widgets. The tree and text are some of the oldest
>    widgets I guess, and I'm pretty sure they wouldn't get by Owen and
>    Tim. So, this category of deprecation is only for legacy stuff.
> 
>    Proposal: call this level of deprecation BROKEN.
>     - immediately remove widgets from API docs
>     - in the first stable release after deprecation, they are 
>       removed from the headers unless GTK_ENABLE_BROKEN
>       is defined
>     - in the second stable release after deprecation, they are 
>       removed entirely
>     - bug reports on the code are ignored
>     - new features are not accepted
> 
>    Rationale: code using these widgets is actively buggy. We need 
>    to confess to our mistake and get rid of them as agressively 
>    as possible, while committing to avoid the problem in 
>    the future.
> 
>    Issue: GtkText is used quite a bit. One possibility: I just noticed
>    that the GtkText interface is really small. I think it might be
>    pretty easy to emulate with the new text widget; if only the public 
>    API functions are supported, and subclasses of GtkText are not 
>    supported, I'm wondering if I could reimplement GtkText in terms 
>    of GtkTextView in only a few days. At that point we could 
>    move GtkText into deprecation category c) instead of a). It 
>    might not work though.
> 
> b) Little-used bloat not of general interest, e.g. GammaCurve.
> 
>    Proposal: call this level of deprecation OVERSPECIALIZED and 
>    is treated the same as BROKEN.
>     - immediately remove widgets from API docs
>     - in the first stable release after deprecation, they are 
>       removed from the headers unless GTK_ENABLE_OVERSPECIALIZED
>       is defined
>     - in the second stable release after deprecation, the code 
>       is removed entirely
>     - bugs are fixed in the code (it is supported)
>     - new features are not accepted for the code
> 
>    Rationale: BROKEN must go away quickly because it's buggy.
>    OVERSPECIALIZED can go away quickly because few people use it.
> 
> c) Replaced by a better alternative, e.g. GtkPixmap, GtkCList.
> 
>   Proposal: Call this level of deprecation REPLACED. 
>    - in the first stable release after deprecation, allow 
>      users to build without these interfaces in the headers
>      by defining GTK_DISABLE_REPLACED.
>    - in the second or later stable release after deprecation, if the
>      maintainers think removing the code eventually is worth some user
>      pain, they can change the default so that you have to define
>      GTK_ENABLE_OLD_REPLACED to get the interfaces, and remove the
>      interfaces from the API docs.
>    - if the widgets ever become little-used, they can be removed.
>      The soonest removal is the third stable release, but if 
>      it appears the pain will be too great, it can be postponed.
>    - bugs in the code are fixed
>    - new features are not accepted for the code
> 
>   Rationale: These widgets aren't useful in new apps, but 
>   unlike category a) they do work and are maintainable, and 
>   unlike category b) they are in pretty widespread use.
>   However we'd like to trim the bloat someday; so we gradually 
>   discourage their use and ultimately phase them out.
>   "little-used" is a subjective judgment, the GTK+ maintainers
>   have to make the call.
> 
> 
> General notes about deprecation:
> 
>  - we only use deprecation for large features. Each version of GTK+ 
>    will change small things, as long as the small changes are easy 
>    to fix and break compilation. For example, a function may 
>    acquire an additional argument. We try to avoid that, but it 
>    will happen in small cases and be documented in the release notes.
>    Changes that silently break your code without preventing
>    compilation are avoided like the plague, however. We also try to 
>    add compat #defines for these kinds of changes, gtkcompat.h 
>    contains those. Compat #defines are only present in one stable 
>    release, unless they're very widely used in the judgment of 
>    the maintainers, and go away after that.
> 
>  - some master document should list all deprecated interfaces,
>    deprecation level, the replacement interface if any, etc.
>    the GTK+ FAQ should point to the document, the release notes
>    should list changes to it.
> 
>  - API docs should be amended to contain the deprecation level of an
>    interface as prominently as possible (ideally, we could hack
>    gtk-doc to actually put a deprecation level notice next to every
>    function in a section, for example...)
> 
>  - header files will of course contain the #ifdef
>    GTK_DISABLE_REPLACED, etc. so users can see deprecation in the 
>    headers.
> 
>  - the general GTK+ trend should be toward fewer and fewer changes 
>    between stable releases, so the scary amount of deprecations from 
>    1.2 to 2.0 is not indicative of future plans.
> 
> Once we agree on a policy I'll prepare an initial list of interfaces
> in each category, then when we agree on that do the initial
> deprecation list, API doc changes, and conditional compilation.
> 
> I just noticed I've written all this for GTK+, but we may as well use
> the same policies for GLib, GDK, etc.  We'd have
> G_ENABLE_BROKEN, PANGO_ENABLE_BROKEN, GTK_ENABLE_BROKEN,
> etc. separately for each lib, so that using one broken interface
> doesn't force you to turn them all on.
> 
> Havoc
> 
> 
> 
> 
> _______________________________________________
> gtk-devel-list mailing list
> gtk-devel-list gnome org
> http://mail.gnome.org/mailman/listinfo/gtk-devel-list
>