[Rubygems-developers] Versioning policy input

[Eivind Eklund]

I was told be Mauricio that there was a discussion on library version
numbering going on.  Below is a quick partial proposal and rationale
based on how this is done for the dynamic library schemes used in
FreeBSD.  Please take this as well-intended input: What we all want (I
think) is to have an overall well-functioning 'library scene' /
'application scene' for Ruby.


A quick note on my background (so you can better evaluate if you want to
listen to the aspects of this that are opinions or not): I've worked with
FreeBSD for over 7 years now, and we've had to go through a number of
the problems in practice, both specifically for libraries, and for
packages that are depended on to provide service through some specific
system separately.  This is the only major exposure I've had to the
problem space.



Rationale for having "true versions":
    Without "true versions", it is impossible to know what is an
    upgrade or not, and it is impossible to know what will work
    together or not.  This means that installing packages will still
    be a "dependency hell" - it is not possible to know what packages to
    install together to make things work without reading the docs, and
    specifically getting the versions that are listed there.  It is not
    possible to mechanically find out what will work together.  Etc.

Proposal:
    Add a separate field "APIVersion" with a version number to the GEM spec,
    which specifies API revisioning, and is rigidly formed for that purpose.

Proposed version format A:

    Single version number X, which is an integer.  The integer is
    increased whenever there are incompatible library changes (both
    extensions and direct changes).

    This is based on the ELF versioning system we presently use in
    FreeBSD.  It is the minimal versioning necessary to be able to make
    things work.  We switched to this at least partially because the
    system below was deemed to complex.  The complexity had led to two
    problems:
    (1) It was more work to implement (I think the single major version
        is the standard for ELF, too)
    (2) People had problems understanding the below scheme, and it
        was easier to explain the simple version scheme.


Proposed version format B:

    X.Y.Z, where X is "major version", Y is "minor version", and Z is patch
    version.

    X is bumped (increased by one) each time the library has incompatible
    API *changes*.  Whenever a method that worked before is
    removed or has its parameter set changed, X is increased by 1, and Y
    and Z are reset to 0.

    Y is bumped each time the library API is *extended*. 
    Whenever a new method is added, or a method starts being able to
    work with a broader set of parameters, Y is increased by 1, and Z is
    reset to 0.

    Z is bumped each time the library gets a bug fix or other
    enhancement that does not influence the API.


    This is based on the a.out library versioning scheme previously used
    in FreeBSD.  As far as I know, this is basically complete (unless
    you want to start tracking individual features of the library).

-- 
Running Debian GNU/Linux Sid (unstable)
batsman dot geo at yahoo dot com

And Bruce is effectively building BruceIX
	-- Alan Cox


----- End forwarded message -----