Re: Improve versioning algorithm description

[Bob Friesenhahn]

On Tue, 22 Sep 2009, Ralf Wildenhues wrote:

> The current text in the "Updating version info" node is seen as hard to
> understand by some users, IIRC we've had a few reports about this in the
> past.  Richard made me try to reformulate it now.
>
> What do you think about this additional explanation?
> OK to apply (and ok to add you to THANKS, Richard)?

This explanation is very useful.  Please apply.

Bob
>    Improve versioning algorightm documentation.
>
>    * doc/libtool.texi (Updating version info): Repeat the
>    algorithms in different, hopefully simpler terms.
>    * THANKS: Update.
>    Report by Richard B. Kreckel and others, several times.
>
> diff --git a/doc/libtool.texi b/doc/libtool.texi
> index 08a44c4..cb6ec80 100644
> --- a/doc/libtool.texi
> +++ b/doc/libtool.texi
> @@ -2879,6 +2879,37 @@ Instead, use the @option{-release} flag (@pxref{Release 
> numbers}), but be
> warned that every release of your package will not be binary compatible
> with any other release.
>
> +The following explanation may help to understand the above rules a bit
> +better: consider that there are three possible kinds of reactions from
> +users of your library to changes in a shared library:
> +
> address@hidden 1
> address@hidden
> +Programs using the previous version may use the new version as
> +drop-in replacement, and programs using the new version can also work
> +with the previous one.  In other words, no recompiling nor relinking
> +is needed.  In this case, bump @var{revision} only, don't touch
> address@hidden nor @var{age}.
> +
> address@hidden
> +Programs using the previous version may use the new version as
> +drop-in replacement, but programs using the new version may use APIs not
> +present in the previous one.  In other words, a program linking against
> +the new version may fail with ``unresolved symbols'' if linking against
> +the old version at runtime: set @var{revision} to 0, bump @var{current}
> +and @var{age}.
> +
> address@hidden
> +Programs may need to be changed, recompiled, relinked in order to use
> +the new version.  Bump @var{current}, set @var{revision} and @var{age}
> +to 0.
> address@hidden enumerate
> +
> address@hidden
> +In the above description, @emph{programs} using the library in question
> +may also be replaced by other libraries using it.
> +
> +
> @node Release numbers
> @section Managing release information

--
Bob Friesenhahn
address@hidden, http://www.simplesystems.org/users/bfriesen/
GraphicsMagick Maintainer,    http://www.GraphicsMagick.org/