Platform policy question: API compatability in minor releases

[Duncan Coutts]

Hello everyone,

We (the platform release team) have a policy question about the Haskell
Platform. We're asking here because we think the libraries list is the
right authority to decide.

The Haskell Platform concept calls for major and minor releases. 

      * The point of major releases is to update the set of common
        packages we all use. That is, to specify which packages and
        which versions (corresponding to APIs). The target is to have
        major releases every 6 months.

      * The point of minor releases is to support a major release across
        a range of operating systems over time and respond to bugs that
        are discovered in a library or tool subsequent to their release.
        The target is to have 2-3 minor releases after major releases at
        intervals on the order of 4-6 weeks.

The question is this:

        Should we allow compatible API additions to a library in a minor
        release of the platform?
        
        The choice is between allowing only bug fixes in minor releases,
        or also allowing new features that add APIs but do not change
        any existing APIs.

It is clear that incompatible API changes must not be allowed in minor
releases. On the other hand, bug fixes that do not change the API at all
are ok.

Let me put some arguments in each case:

Allow compatible API additions

        If the change is compatible then it does not break any existing
        programs, so it should be allowed. Any program that works with a
        platform particular release will continue to work with
        subsequent minor versions. This is standard backwards
        compatibility policy.
        
        Getting minor feature improvements is sufficiently important
        that it is too long to wait 6 months for the next major release
        of the platform.

Allow only bug fixes, no API additions

        Forwards compatibility is important too. A developer should be
        able to make a package and test it with platform version X.Y.2
        and it should still work for a user with version X.Y.1. That way
        we do not force upgrades on users all the time. Users should
        only have to upgrade to a later minor release if earlier
        versions didn't build/install/work on their OS, or if they hit
        some particular bug which is fixed in a later minor release.
        
        There is no need for API changes in minor releases. Maintainers
        can make a release with just the bug fixes to go into a minor
        platform release and then make additional releases with new
        features on Hackage. Users who want the new features can get the
        new package version from Hackage.
        
        API additions in minor releases works against the distinction
        between major and minor releases.

I hope that's not too biased a summary (I'll post my own opinion
separately). If there is anything that I should clarify then please ask.

So please post your thoughts and arguments. I hope we can come to a
conclusion within a few days. This is a timely issue because we aim to
make a minor release on the 1st of June and we want to finalise the list
of package versions two weeks prior, by the 18th of May.

http://trac.haskell.org/haskell-platform/wiki/ReleaseProcess


Duncan