Dependencies/backwards compatibility in Hackage

Fawzi Mohamed fawzi at
Mon Feb 5 12:29:41 EST 2007

> [...]
> 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 

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

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

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  

> - 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  

> - 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  
If problems arise in a package one should modify its compatibility  


More information about the cabal-devel mailing list