Dependencies/backwards compatibility in Hackage
bringert at cs.chalmers.se
Mon Feb 5 11:41:14 EST 2007
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.
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.
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
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.
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".
- 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.
- 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
- 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?
More information about the cabal-devel