[Haskell-cafe] Re: [Haskell] Re: Trying to install binary-0.4

[Ross Paterson]

On Tue, Oct 16, 2007 at 01:08:49PM +0100, Simon Marlow wrote:
> So rather than keep replying to individual points, I'd like to make some 
> concrete proposals so we can make progress.
>
> 1. Document the version numbering policy.
>
> We should have done this earlier, but we didn't.  The proposed policy, for 
> the sake of completeness is: x.y where:
>
>   x changes ==> API changed
>   x constant but y changes ==> API extended only
>   x and y constant ==> API is identical
>
> further sub-versions may be added after the x.y, their meaning is 
> package-defined.

This should be required for at least the GHC boot packages (and encouraged
for others).

I would make "API extended only" a bit more precise: any module that uses
explicit import lists will not be affected by the changes.  So one can
add classes, types and functions, but not instances (except where either
the class or the type is new).  You probably can't add data constructors
or fields, and have to be careful with new methods.

I'd also prefer that major versions used two numbers, because that's
common now, it supports the experimental versions 0.x apfelmus mentioned,
and it makes it easier to leave room for development versions (possibly
using an odd-even scheme).  If you make your development repository
available, and it contains API changes, you'll want its version number
to have a larger major number.