Library versioning

[Fredrik Roubert]

The question below (which I think is a discussion that belongs on this
mailing list), about how libphonenumber version numbers get assigned
and the relationship between code changes and metadata changes, came
up in this discussion about Debian packaging of libphonenumber:

https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=741258

--
Fredrik Roubert
rou...@google.com


---------- Forwarded message ----------
From: Daniel Pocock <dan...@pocock.com.au>
Date: Mon, Jun 2, 2014 at 2:33 PM
Subject: Re: libphonenumber packaging, libre2, ...

[...]

One thing stands out for me - the package numbering, e.g.
libphonenumber5, libphonenumber6, ...

The SONAME in the file appears correct:
$ objdump -p ./cpp/build/libphonenumber.so | grep SONAME
SONAME libphonenumber.so.6

If you change the ABI number regularly, then it will be hard to push
updates to stable distributions (e.g. Debian stable, Ubuntu LTS, EPEL).
Ideally, if updates are just data changes (to recognize new area codes
and numbering plan changes) then they would be in some separate package
that can be distributed through $(stable)-updates - just like anti-virus
patterns, timezones, etc:
https://lists.debian.org/debian-volatile-announce/2012/msg00000.html

The binary ABI and the developer API would stay the same for a given
Linux version. I don't want to deter you from adding new features or
make it more tedious to support, but would it be possible to distribute
the pattern data separately in such a manner?

The other problem with the package name is that each time there is a new
package name anywhere in the control file (e.g. a libphonenumber7
package) then the next upload to Debian will need to go in the FTP NEW
queue for manual approval, that adds a delay of 1-4 weeks. If the
package names haven't changed, then uploads to Debian (and propagation
to Ubuntu) happen automatically within a few hours. Usually if this
happens no more than once per year it is OK.

If the version number is really significant, maybe the Java packages
should also be named libphonenumber${VERSION}-java? Does anybody care
either way?

[...]

[Shaopeng]

Hi Daniel,

Version numbers are not very significant to us. As the library has entered a stable stage, we anticipate very rare changes in the API. The most of the changes will be data-related, and occasionally bug fixes to the implementation of the code. As a result, we will mostly only update the minor version number of the library going forward, and keep the major version number at v6. Would this address your concern?

Having the data in a separate package is doable, but does require a non-trivial engineering effort. The team has committed on other projects, so it won't happen any time soon unless someone on this discussion list is willing to contribute time to carry out the work.

Cheers,

Shaopeng 

--
You received this message because you are subscribed to the Google Groups "libphonenumber-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to libphonenumber-di...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Lara Rennie]

Just to agree with Shaopeng - I think we can safely say that we'll only update a major version number going forward if the API changes in a non-backwards compatible way.

Did you need help with i18n? Help us help you: go/i18n-emea-feedback 

[Daniel Pocock]

On 04/06/14 10:23, Lara Rennie wrote:
> Just to agree with Shaopeng - I think we can safely say that we'll only
> update a major version number going forward if the API changes in a
> non-backwards compatible way.
>
>

Ok, that is good news - that will make it easier to publish each new
version of the package and make updates available to users of stable
distributions.

A complete API freeze is not necessary - it is quite OK to add new
methods, for example, just as long as all existing methods continue to
accept the arguments they accept today.

For C/C++ it is slightly more restrictive than Java - for example,
making changes that impact the size of classes (such as adding an extra
member variable) needs to be avoided.

[Lara Rennie]

We don't want to get version numbers out of sync...

At the moment we have major.minor.data -> so if we added an extra member variable we'd increment the "minor" thing at the moment.

[Daniel Pocock]

On 04/06/14 12:28, 'Lara Rennie' via libphonenumber-discuss wrote:
>
> 2014-06-04 12:23 GMT+02:00 Daniel Pocock <dan...@pocock.pro

> <mailto:dan...@pocock.pro>>:

>
>
>
> On 04/06/14 10:23, Lara Rennie wrote:
> > Just to agree with Shaopeng - I think we can safely say that we'll
> only
> > update a major version number going forward if the API changes in a
> > non-backwards compatible way.
> >
> >
>
>
> Ok, that is good news - that will make it easier to publish each new
> version of the package and make updates available to users of stable
> distributions.
>
> A complete API freeze is not necessary - it is quite OK to add new
> methods, for example, just as long as all existing methods continue to
> accept the arguments they accept today.
>
> For C/C++ it is slightly more restrictive than Java - for example,
> making changes that impact the size of classes (such as adding an extra
> member variable) needs to be avoided.
>
>
> We don't want to get version numbers out of sync...
>
> At the moment we have major.minor.data -> so if we added an extra member
> variable we'd increment the "minor" thing at the moment.
>

Adding an extra member variable in Java is OK

In C++, when you add an extra member variable, you MUST increment the
ABI number (the number that appears in the SONAME). At that point, you
will probably increment the major version number too. Here is a blog
that explains it and suggests one way to work around this:

http://www.murrayc.com/permalink/2007/03/12/abi-stability-of-c-libraries/

Here is a more comprehensive list of things that will cause ABI breakage:

http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C++

When you make such updates, people MUST recompile any code that links to
your code. They may not need to patch their code at all, but when they
recompile, it will take into account the new class sizes. By
incrementing the ABI number, you force people to make that recompile.

[Shaopeng]

Thanks a lot for the links! They are very informative. We will take note of the dos and don'ts in our future releases.

Cheers,

Shaopeng