Decide on version numbering scheme about erfa

[olebole]

As I wrote in the mailing list: I'd vote for adopting the astropy scheme, starting with 0.1 for the pre-release, and then having 1.0 as soon as the open issues are fixed. SInce there is no direct linkt to SOFA, changes from IAU (new versions) and from third-party could be handled equally.

[timj]

The philosophy of ERFA is meant to be that it is tracking SOFA so I see the parent version of SOFA as being important information. The plan is not to develop ERFA independently and add lots of new features.

[olebole]

I'll just move the discussion in the mailing list here, so here is a (lightly modified) copy:

@timj writes:

On Mon, Aug 12, 2013 at 10:34 AM, @olebole wrote:

@taldcroft writes:

I propose that the first formal release of ERFA should roughly coincide with astropy 0.3, even though they are unbundled.

Why do you think they will diverge? ERFA is tracking SOFA. I didn't think we were developing ERFA independently. Patch releases to do with building tweaks were all that I was envisaging.

I mean that the ERFA version will diverge from astropy: while astropy is under heavy development (and will stay so, hopefully for the future :-)), ERFA is supposed to be stable.

I vote for being explicit and deriving the version number from the SOFA version that it is derived from.

One could; however I would not put too much information into this number. When you look at the evolution of SOFA (and extrapolate that to the future of ERFA), there was not soo much change over the years. the "yyyymmdd"-information does not give much and is less handy than just a "1.0", or "1.1" or so. Except leap seconds.

Also, since erfa is not sofa, we would need to add its own release information. for sofa_c-20120301_a, we had an erfa-20120301_a_1, erfa-20120301_a_2 etc.

And if IAU decides just to adopt changes proposed by ERFA, they release a (let's say) sofa-20120301_b, which we start to integrate into a erfa-20120301_b_1 which is identical to the release before since they just adopted our changes. Sound a bit confusing to me.

However, at the end I really do not care. I happily will take any solution and create an appropriate Debian release number (except that I then will put dots in the date string for readability, as I did for iausofa_c).

Best

Ole

[embray]

SOFA has an annoying date-based version scheme, however. Would much rather use a semver-compatible version. There doesn't have to be a one-to-one mapping of every SOFA version to every ERFA version either--just update the ERFA version every time it's updated from the latest SOFA. Note the SOFA version it's derived from in the docs somewhere.

[sergiopasra]

I would go for semantic versoning, just for simplicity.

[taldcroft]

I'm also +1 on semantic versioning starting at 1.0, with something in the README.rst (for example) that indicates the version of SOFA that was used to derive ERFA. I presume the major version would increment with a new release of IAU SOFA, with minor versions indicating local patches. @timj - it seems most are in favor of semantic, are you OK with that?

[timj]

@taldcroft I'm happy with your approach.

[eteq]

Semantic would be my preference as well, with an explicit mention of the last version number recorded in the README.rst (or possibly INFO) as @taldcroft suggested.

[astrofrog]

I'm fine with the semantic versioning approach, and I think that we should indeed start at 1.0. Note that these versions will not always match exactly with SOFA releases due to patches such as the one @taldcroft is suggesting, so we can basically say e.g. 1.0 is the same as SOFA version x with the following differences.

[embray]

In addition to having the version in the README can we please have it in a header file as well. I would like it both as a string and as three integers like:

#define ERFA_VERSION "1.0.0"
#define ERFA_VERSION_MAJOR 1
#define ERFA_VERSION_MINOR 0
#define ERFA_VERSION_MICRO 0

I think this is a must-have. Also please no versions as floats (I'm looking at you CFITSIO). Also these can be added at build time using a config.h.in that gets built into config.h. The version can just be parsed out of a single file so it only needs to be updated in one place.

[olebole]

I would more care about having it in the library, so that a program can check at runtime which version it uses. Just having it in the header is not enough, since libsofa.so can be upgraded after compliation. And so, astropy cannot check whether it runs with the most current version.

[embray]

@olebole Sure. I think there should be both. In the library there can be a global variable like:

char *liberfa_version_string = ERFA_VERSION;

also

typedef struct {
    unsigned int major;
    unsigned int minor;
    unsigned int micro;
} _liberfa_version_type;

_liberfa_version_type liberfa_version = {ERFA_VERSION_MAJOR, ERFA_VERSION_MINOR, ERFA_VERSION_MICRO};

Add the appropriate extern declarations in the header.

[sergiopasra]

@embray autoconf provides a PACKAGE_VERSION C macro with the value of the version of the package set in AC_INIT. The macro is written in config.h. So we can do:

#include <config.h> 

char *liberfa_version_string = PACKAGE_VERSION;

For the MAJOR/MINOR/MICRO numbers, I'm not aware of standard autotools functions, but I can write one that splits PACKAGE_VERSION and defines PACKAGE_VERSION_MAJOR, etc, in config.h

[sergiopasra]

pkg-config files have a version field and it can be used to check for particular versions of libraries

You can check the version of the library in the command line with:

 $ pkg-config --version erfa
 1.1.0

or inside a configure script provided by autotools with:

  PKG_CHECK_MODULES([ERFA], [erfa >= 1.0])

In this last case, the check fails if the version of erfa is less than 1.0

I'm not familiar with cmake, but I'm sure that it supports pkg-config files

[sergiopasra]

There is another number that we have to provide, the library interface version. This goes in the soname of the shared libraries and its used at run time by the system loader to determine if the program can be run with the current version of the library.

For example, if a program was compiled with a version with soname liberfa.so.0, it will not work if the soname of the library in the system is liberfa.so.1. Thus, the soname is changed on API breackages.

The current Makefile of erfa does not provide soname, but #5 does. I propose to follow the libtool convention to provide the soname.

This convention is followed by lots of open source libraries. If you look into a library directory in your system you will find files like this:

libfoo.so.0.3.0
libfoo.so.0
libfoo.so

where the last two files are links to the first file. A library like this probably follows the libtool convention.

[eteq]

@embray - are the options autoconf gives (that @sergiopasra outlined here) good enough as far as you're concerned? And are you attached to the major/minor/micro enough that it's worth getting these things parsed out from the char*, or is PACKAGE_VERSION mostly acceptable?

So @sergiopasra , based on your discussion of the soname, should we adopt the convention that the major be incremented for all API changes? Or only those that are backwards-incompatible?

[embray]

I should be easy enough to split PACKAGE_VERSION. It's really useful to have the version split into separate numbers so that you don't have to implement version parsing every time you want to compare some version strings. But if it's a hassle for getting this issue closed we can just open a separate issue about it to address when a specific need arises.

[sergiopasra]

@eteq I believe that major should be updated only in backwards-incompatible changes. Minor for backwards-compatible changes and micro for no changes in the API.

[sergiopasra]

BTW, I have added the code to split the version string in commit sergiopasra@789eb8e

[eteq]

Alright, so any objections to this scheme:

• Major changes only when API is not backwards-compatible
• Minor changes when API changes but is backwards-compatible
• Micro changes for bugfixes.

@olebole @embray @timj @astrofrog ?

[timj]

@eteq fine.

[eteq]

Hah, it just occurred to me that what I typed above is very nearly the definition of semantic versioning, so we're back where we started :) but good we got the issues flushed out

[embray]

Yep, pretty much :)

[astrofrog]

Sounds good!

[olebole]

Sorry, I didn't see that this is still open. Fine for me as well. May be closed :-)

[eteq]

Oops, yeah, I actually meant to close this when #5 was merged. Thanks for the reminder, @olebole