Re: How to indicate API version properly (taking in account next release)?

[Richard Frith-Macdonald]

On 9 Aug 2006, at 11:14, Quentin Mathé wrote:

> Hi,
>
>
> I would like to know whether there is any way to indicate the next  
> GNUstep release for GS_API_VERSION macro.
> For example, when you add a new method, it will be available only  
> with the next release, but at the time you commit header/ 
> implementation update related you cannot know for sure what will be  
> the next version number of the library. The maintener can decide to  
> do either a minor release or a major release then the release  
> number will vary.
>
> If the latest release is related to the macro:
> #if GS_API_VERSION(011300,GS_API_LATEST)
>
> The next release could be either 1.0, 0.12 or 0.11.4… Here is the  
> prGNUoblem :-)
> That means you have to guess the next release number (where your  
> new features will be introduced).
>
> Some kind of macro like GS_NEXT_RELEASE associated with a script  
> run to replace at release time could prove to be useful.
> #if GS_API_VERSION(GS_NEXT_RELEASE, GS_API_LATEST)
>
> Any already available solutions or suggestions?

I understand the problem, but I don't think the best solution is to  
add new macros and scripting.  Rather, I think it's to adopt a  
slightly more rigorous approach to making releases.  What I propose  
is this ...
When we make a release, we make a branch in svn into which any  
bugfixes will be applied.
Immediately after making the release, we increase the minor version  
number in trunk.

After a release, if we need to make a bugfix release, we do it by  
incrementing the subminor version number in the branch and releasing  
a snapshot of the branch at that point.  We don't add new features in  
bugfixes, so there is no issue with version macros.

Any API changes added to trunk will be in the next non-bugfix  
release, so the version number to put in the macros is the version  
number of the current trunk code.

It is possible that the maintainer may decide not to actually release  
the version in trunk, but to jump directly to a new major version  
number ... this does not matter, since the new version number is  
guaranteed to be at least as high as the value put in trunk  
immediately after the last release.

eg.
we release 1.14.0
we move trunk to 1.15.0
we add API tagging it as available from 1.15.0 onwards
we decide to release 2.0.0 rather than 1.15.0 ... but that's OK, the  
new API available from 1.15.0 onwards is automatically available in  
2.0.0, it doesn't matter than 1.15.0 was never released.

So, the only 'work' needed for this solution is to create the bugfix  
branch for each non-bugfix release, and increment the minor version  
number (and set the subminor version to zero) in trunk immediately  
after any non-bugfix release.

> By the way, it's not easy to find the macros GS_API_VERSION and  
> OS_API_VERSION in the documentation because there is no links to  
> them in the -base Intro section (where API versioning is  
> introduced). Some examples in the documentation would be useful too.

Good point ... I've updated the documentation in SVN to link from the  
intro into the macro reference documentation.  There are a few simple  
examples, but better / more extensive examples would be welcome.