[...]
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
_______________________________________________
cabal-devel mailing list
[email protected]
http://www.haskell.org/mailman/listinfo/cabal-devel
