Re: Documenting API versions

[Gerold Rupprecht]

On 2005-05-09 15:08:04 +0200 Richard Frith-Macdonald 
<richard@brainstorm.co.uk> wrote:

> Hi ... nice to hear from you again ... I hope you got home from 
> FOSDEM 
> without too much trouble.

After all the rush I had time to shop at the airport - one of the 
worst snowstorms in Geneva kept the plane from leaving Brussels - hope 
you enjoyed the taxi ride even if I was a bit stressed.


> On 2005-05-09 12:48:52 +0100 Gerold Rupprecht <geroldr@bluewin.ch> 
> wrote:
>
> > First, thanks for your working on this.
> >
> > I think what you are trying to do is say something along the lines
> >
> > ValidFromOS xxx                         To:NULL
> > ValidFromOSVersion xxx          To:NULL
> > ValidityStatus
> > ValidFromDate xxx                       To:NULL
>
>
> I think we are talking about operating system version/release, and 
> are not 
> considering specific dates (though I guess we could lookup dates of 
> various 
> releases).
>
> > As seem to have the following axes:
> > OS,
> > OSversion,
> > Current / depreciated / removed
> > Date.
>
> I think in terms of operating systems, we consider there to be two 
> sets of 
> versioning.
> First is the OpenStep -> OPENSTEP -> MacOS-X line ... ie 'official' 
> NeXT/Apple releases.
> Second is the GNUstep line.
> We want to consider two GNUstep lines, one for the base library and 
> one for 
> the gui library, as we use different versioning for the two.  
> However, since 
> the base and gui headers/documentation are separate, I think we can 
> probably 
> manage that quite simply.
> We haven't really discussed deprecation ... but extending the scheme 
> to 
> include a version of the system at which part of the api was 
> deprecated is 
> pretty simple.
>
> > If the constraints are NULL, this would imply that the code is valid 
> > for:
> > All supported OSes
> > All versions
> > (Current is implied)
>
> Yes.  Though in the proof of concept code I added, I use a specific 
> marker 
> '9999' as meaning the current release ... in a final version I would 
> prefer 
> to use a more readable marker or (better) use extra macros with only 
> one 
> argument each.
> So in the quick hack, the markup for a group of methods introduced in 
> macos 
> 10.3 and in GNUstep 1.02 would be -
>
> #if OS_API_VERSION(1003, 9999) && GS_API_VERSION(0102, 9999)
> // a load of method declaractions here
> #endif
>
> but a more plished version might use
> #if OS_API_VERSION(1003, NEVER) && GS_API_VERSION(0102, NEVER)
> or
> #if OS_API_VERSION(1003) && GS_API_VERSION(0102)

I think the NEVER indicator better than 9999 - easier to understand.

> > If a date is given, it indicates the date the validity began / ended 
> > (removal date or depreciated date).
> >
> > Can some of the date information be recovered from CVS ?
>
> I don't think we are looking at dates ... just versions.

I think dates are important to document too. This is important to be 
able to defend the project from any possible litigation. It may also 
help any other open source project by making it easier to identify 
"prior art" (help stop software patents!).

> I think Sheldon's summary of his approach is pretty good (seems clear 
> to me), 
> but his summary of mine (as I hope is apparent from my emails) is 
> only 
> vaguely similar to what I was suggesting ... In particular, all but 
> the last 
> of the advantages he lists for his approach also apply to mine 
> because, as I 
> keep trying to make clear, I'm advocating a superset of the 
> functionality 
> (adding compile-time checking that a program doesn't use api it 
> shouldn't) 
> and a modest simplification of the markup task (markup a whole chunk 
> of the 
> api in one go)  ... It could be easily modified to be applicable to 
> other 
> projects too I guess.
>
> The reason for this is easy to understand ... my approach was to take 
> Sheldon's suggestion of having more detailed versioning, combine it 
> with the 
> best points of the existing versioning, and refine that with 
> suggestions from 
> David, Adrian et al, with the aim of maximising both functionality 
> and 
> simplicity.

Best wishes,

Gerold Rupprecht