deprecation policy

[Havoc Pennington <hp redhat com>]

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