[gdal-dev] Policy for C/C++ API for GDAL 2.0 ?

[Even Rouault]

Hi GDAL developers and users (actually, developers of other projects using 
GDAL ;-)),

This issue was raised incidently in the "[gdal-dev] VRTComplexSource with a 
LUT, proposal" thread at http://lists.osgeo.org/pipermail/gdal-dev/2012-
May/032872.html . 

I think it is good time to discuss now what we want to allow, or not, for GDAL 
2.0, as far as the C/C++ API is concerned.

---------
C API
---------

Up to now, the signature of functions added in the GDAL/OGR C API has never 
changed, once they have been added.

What should be the rule for GDAL 2.0 ?

1) do not change the signature of any function already present in the C API. 
If breaking changes are necessary, then introduce "FooEx", or "Foo2" versions 
of those functions as done in the past. The drawback of that approach is that 
the API becomes cluttered.

2) do not change the signature of any commonly used functions, but allow 
changes in marginally used functions. The definition of commonly functions 
w.r.t marginally used ones is a bit arbitrary. Looking at the symbols used by 
popular Open Source software using GDAL C API could give a clue in case of 
doubt (MapServer, QGIS, GRASS, PostGIS, or in-tree GDAL utilities using C API  
...). 

3) allow changes even in commonly used functions.

Options 2) or 3) would likely require other projects to have #if GDAL_VERSION 
>= 2000 in some places if they plan to support older GDAL versions. Unless 
they plan to update their dependency requirements when they release a newer 
version of their project (Project XX version < 1.Y depends on GDAL < 2.0. 
Version >= 1.Y depends on GDAL >= 2.0).

-------------
C++ API
-------------

As far as the C++ API is concerned, the policy up to now was that minor 
changes between GDAL 1.X version and GDAL 1.(X+1) were OK. Generally, the 
changes have been the addition of new optional arguments, that only required 
recompilation to solve the change of ABI, but did not require code changes.

For GDAL 2.0, I believe that most major changes could occur, especially if the 
OGR "grand unification" occurs, but for now, I don't know the impact that that 
might cause.

-------------------------------------------------
Syntax of command line utilities
-------------------------------------------------

A bit out of topic, since it is about UI and not API. But a lot of scripts in 
the wild call popular GDAL command line utilities. Changes in their syntax 
would cause potentially more headaches, given the larger number of users 
w.r.t. developers using GDAL ;-) The page at 
http://trac.osgeo.org/gdal/wiki/GDAL20Changes lists a few changes that have 
been proposed (just as a reminder : nothing listed there is officially vetted).

The same question also arise with the API of the various bindings languages.

Feedback welcome !

Best regards,

Even