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