Foreign.destructArray

[Alastair Reid]

SimonM:
> I'm surprised that you're having so much trouble [with APIs changing
> between GHC releases] though.

I'm not for a number of reasons:

- The libraries that come with GHC are huge and very few of them are
  completely stable.  Even the H98 libraries change as H98 is refined.

- The statement that 'deprecated' means 'will not change until the next
  major release' isn't very satisfactory because:

  1) People might disagree about what a major version is.  The second
     sentence in this quote from SimonM suggests that the ':-)' is
     a typo and SimonM really doesn't regard 5.02->5.04 as a minor
     version change.  

     > 5.02-> 5.04 is a major version change :-) We only promise not to
     > break APIs in patchlevel releases (eg. 5.04->5.04.1 won't break
     > anything).

     I must be misinterpreting because such an interpretation of 
     version numbers would be highly surprising and the recent rate
     of 'major' releases would be surprisingly high.

  2) The timing of GHC releases is unlikely to be a useful measure to 
     people relying on GHC in their project.  Much more useful would be
     'will not change before the POPL deadline' or 'will not change
     before our IPO'.  That is, entities should be deprecated for
     a time period not a release cycle.

- AFAIK, there's no mechanism (manual or automatic) in place to check
  that things go through a suitably long deprecation period.

- I've been a GHC user for years (version 0.16 or maybe earlier) and
  seen this happen many times.


To fix this situation (which I believe is common), we probably need
something like:

1) Every entity in the API (type, function, module, etc.) should be
   assigned a 'stable period' such as 'stable until Jan 1st 2003'.

   This assignment can be explicit or implicit.

   Explicit: 
   - add an expiry date to deprecated pragmas.
   - add a new pragma which says that the API is stable until
     a given date but there is no reason to believe that it
     will change after that.

   Implicit: 
   - anything not marked explicitly is as stable as the library
     or library hierarchy that provides it.

2) Have the test suite watch for the disappearance of entities before
   they are due to expire.  

   This might be conveniently done by adding a flag to GHC which dumps
   out all entities and their expiry date.   The testsuite would then report
   any relevant changes since last week (or whatever time period you test on):

   - have any entities disappeared before their expiry date?
   - are any entities past their expiry date?
   - have any expiry dates decreased?

3) GHC's flag to warn about deprecated functions would take an
   optional expiry date as an argument.  GHC would warn about use of
   entities which will expire before then.  Probably on by default.

4) GHC would add a flag to warn about entities which are not deprecated
   (i.e., there is a plan to change) but about entities which are
   not guaranteed not to change before a given expiry date.  
   Probably off by default.

5) Each release would include a list of any entities removed ahead of
   schedule.

   [It's open to debate whether this would do anything other than
   increase the motivation to keep the list small.]


--
Alastair Reid                 alastair@reid-consulting-uk.ltd.uk  
Reid Consulting (UK) Limited  http://www.reid-consulting-uk.ltd.uk/alastair/