Re: Dependencies/backwards compatibility in Hackage

Isaac Jones wrote:

"Sven Moritz Hallberg" writes:

...

Ross Paterson , 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