Dependencies/backwards compatibility in Hackage

[Björn Bringert]

Isaac Jones wrote:
> "Sven Moritz Hallberg" <sm at khjk.org> writes:
> 
>> Ross Paterson <ross at soi.city.ac.uk>, 2007-02-01 12.14 +0000:
>>> We could decide on a standard interpretation of version numbers, e.g.
>>> major.minor.patch.  To support this, we'd want wildcards like 1.13.*
>>> in version ranges.

It would be a bit more tedious to type it every time, but wouldn't 
"HaXml >= 1.13 && < 1.14" be equivalent to "HaXml == 1.13.*"?

>> Sounds compelling, but will everyone want/agree to follow that scheme?
> 
> I think we should just declare such a standard.  Very few people care
> about version numbers outside of ghc-pkg, hackage, and cabal.  If we
> pick something that works for us, I suspect that the majority of
> people will just go along, as long as it's reasonable.
> 
> Does anyone want to declare such a standard? :)

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.


Background:

Cabal package version numbers are non-empty sequences of natural 
numbers, separated by dots. Version numbers are ordered 
lexicographically. This is a proposed policy for how to assign such 
version numbers to library releases.

Assigning version numbers:

Library packages should have version numbers on the format 
major.minor.revision, where major and minor are natural numbers and 
revision is a sequence of natural numbers separated by dots. If the 
revision is the empty sequence, the version number has the format 
major.minor.

Version numbers should be assigned so that software which uses the 
public API of the library should not be broken by an upgrade to a higher 
version with the same major.minor combination.

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


Consequences:

- you must change the major.minor number if you release a version where:
   - you change any exported names, or if you change the type of any
     exported entity to a type of which the old type is not an instance.
   - you export an additional name or module.

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

- you are free to choose the revision number scheme.


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.

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

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


/Björn