From: Austin Ziegler <halostatue@...>
Date: 2005-10-19T01:26:10+09:00
Subject: Re: gem versioning confusion

On 10/18/05, Ara.T.Howard <Ara.T.Howard@noaa.gov> wrote:
> two of these are quite confusing:
>
>  * Version 0.0.1: The initial Stack class is release.
>
> why on earth would all digits begin numbering at zero __except__
> build? seems that it should be version 0.0.0

I personally never release at less than 0.1.0, and often higher than
that.

>  * Version 1.1.0: push now returns the value pushed (it used it return nil).
>
> why would this not be 2.0.0 - remembering we're at 1.0.0 from 'eg 3'?
> clearly code which had done

That probably should. However, I have also broken that "pattern" from
time when it makes sense. As a specific example, I point to PDF::Writer
1.0 vs. PDF::Writer 1.1 where I had to invert the meaning of certain
values. I do not see a problem with necessarily changing the meaning of
some APIs even in non-major versions. Ideally, this would be done over a
period of time. For example, in the upcoming PDF::Writer 1.1.4, I have
several APIs that warn if the wrong parameters are provided -- but it
fixes the parameters up. In PDF::Writer 1.2, I may cause the wrong
parameters for some of these to fail with a message (particularly those
warnings that have been around since 1.1.0 or 1.1.1).

When PDF::Writer 1.3 comes out, they will *definitely* fail with a
message. By the time PDF::Writer 1.5 comes out, however, these APIs will
be changed and there will be no warnings or messages related to these
items. These are evolutions of a particular API interface.

PDF::Writer 2.0, however, makes no API compatibility guarantees at all.
Yes, they'll likely be the same, but those that change between 1.x and
2.x will be documented but not warned or failed with methods. (This is
particularly true when the new core object model is introduced.)

Similarly, with color-tools 1.3, I removed a number of constants from
the Color namespace and put them in Color::RGB. In 1.3, there is a
const_missing that detects the first time any Color constant is used and
prints a warning. In 1.4, the const_missing warning will appear the
first time each individual Color constant used. In 1.5, I will either
eliminate the const_missing (there have, after all, been two versions of
documentation regarding this) or cause it to print every time an
individual Color constant is accessed.

To me, sane API management isn't about version numbers all of the time.
Going to version 1.0 is an important psychological barrier that should
not just be done because of an incompatible API change. The same applies
from going from 1.0 to 2.0. There is a promise of API maturity when
higher version numbers are applied.

-austin
--
Austin Ziegler * halostatue@gmail.com
               * Alternate: austin@halostatue.ca