Dependencies/backwards compatibility in Hackage

[Fawzi Mohamed]

> [...]
> Here's a draft based on Ross's proposal above. Please rip it apart.
>
>
> Executive summary:
>
> Library package version numbers should be on the format  
> major.minor.revision, where major.minor must change whenever the  
> API changes in a backwards-incompatible way. The revision  
> identifier can have any number of segments, allowing snapshot  
> releases etc.

As I said I really like the method used for frameworks on MacOSX (or  
for some libraries on linux) which is described here

http://developer.apple.com/documentation/MacOSX/Conceptual/ 
BPFrameworks/Concepts/VersionInformation.html

major:
The major number means non backward compatible change, and is part of  
the name
(on linux you see for example libreadline.5.so where 5 is the major  
revision).
It is possible to have more than one major revision installed (very  
useful during transitions)

minor:
backward compatible change (additions to the api, bug-fix,...)

revision:
bug-fixes, development (can be absent), I would like to have this a  
lexicographically ordered string, so that one could use a date  
YYYYMMDDTHHMM plus some other "snapshot defining" string, or add a  
fourth non ordered string value

now when a modules says that it needs 3.4.5 it means major=3,  
minor>=4, (if minor==4 rev>=5).

I like the idea of having a tool that checkes the interface changes  
and automatically says if one should change minor or major version  
(it would work most of the time I think, and be very useful).

> [...]Declaring dependencies:
>
> Package dependencies should be on a ranges of version numbers such  
> that for each range, the smallest accepted version number is one  
> that the package works with, and the largest accepted number has  
> the same major.minor combination as a version that the package has  
> been determined to work with. For example, if a package has been  
> found to work with foo 1.2.5 (but not 1.2.4) and foo 1.3, the  
> dependency should be declared as "foo >= 1.2.5 && < 1.4".

a problem with this is that how much it works with future releases is  
difficult to predict.
I major version change specifies a non backward compatible change  
there is a meaningful default: if not specified the package will not  
work with different major vesions, but will work with (higher) minor  
versions.

> - for each release that needs a new major.minor combinaton, you are  
> free to choose whether to increment the major or the minor number.  
> It is suggested that the major number is incremented when the  
> changes are major.

for the resons utlined before unless other feel that it is a too big  
ingerence in the version numbering I think that non backward  
comaptible changes should always increment the major number.

> Suggestions for how to assign revision numbers:
>
> - Revision numbers could be chosen sequentially, for example using  
> "" (or ".0"), ".1", ".2" etc.
>
> - Another level could added to the revision number for snapshot  
> releases, e.g. ".0.20070205", ".0.20070206".
>
> - To avoid confusion, it could be a good idea to not use "x.y" and  
> "x.y.0" for different versions.
>
>
> Problems:
>
> - Packages will often have their dependencies too tightly  
> specified, since many API changes don't all depending packages.  
> However, having multiple versions of a package installed is  
> probably better than random breakage.
>
> - Snapshot releases can't be required to change the major.minor  
> number every time the API changes. Packages could possibly use an  
> odd/even scheme to indicate stability.

maybe one could add a stability flag, or add unstable to the revision  
string

> - Does "the public API" include all exported modules? Or does it  
> exclude semi-public Internals modules etc?

Exported modules has the advantage of being easily checkable, but I  
would allow for extensions of the private api to have the same minor  
number, otherwise development could be more difficult.
On the other hand a hard approach to it might have advantages,  
published modules should respect the rules.
Maybe here a stability flag could be useful.

> - Does "break" include fixing bugs (undocumented behavior) that a  
> depending library relied on?

I would say no, unless it is something that is expected to give major  
problems.
If problems arise in a package one should modify its compatibility  
range.

Fawzi