LSARC/2008/059 - SQLite

[Brian Cameron]

>>> Also, some parts of the API are deprecated and some are experimental.
>>> The API docs (which aren't manpages, BTW), are clear about the stability
>>> attributes of the various interfaces.
>> In that case, we should make our stability attributes match the ones
>> advertised by the software authors.  Use "Uncommitted" or better for
>> the things that are in fact stable, and "Volatile" and "Obsolete" for
>> the experimental and deprecated parts.  Just pass the upstream
>> guarantees to the downstream users.
> 
> I agree in this specific case, but should we generally do this where
> possible?
> 
> The upstream community may have an interface stability taxonomy that is
> roughly compatible with ours, and maybe even a similar release binding
> taxonomy, but it's unlikely that their releases will be timed at all
> with ours.

I don't think external interface stability levels need to match Sun's
stability levels.  The GNOME community, for example, provides ABI
compatibility for all libraries in the "GNOME Platform".  However,
we only support a subset of these as Committed in Solaris.  This is
for several reasons:

- We feel a good GNOME application should be written with just the
   libraries we recommend
- The JDS team is not interested in supporting the other libraries at
   a "Committed" or "Stable" level.
- Some of the libraries (but not all) which we exclude have future
   planned deprecation dates.

> Or is that not a concern because if the upstream community makes "major"
> releases then we can just ship multiple versions of it in the next
> micro/patch release of Solaris (or OpenSolaris release vehicles)?
> Multiple versions of libraries can be problematic, after all, though I
> believe in most cases there's always reasonable guidance that can be
> given to avoid DLL hell.

That is also a very real concern.  Does Sun want to restrict what we
can do in the future if the external community breaks ABI or has a
different understanding of what stability means than we do?

>> I don't see a good reason to make things hard on future projects that
>> might want to use these interfaces by making a lesser promise to
>> Solaris users than the software author does.
>>
>> (It doesn't matter whether the documentation is in man page format, so
>> I'm not sure I understand your parenthetic comment.  Care to
>> elaborate?)
> 
> (I was worried that using anything other than Volatile might mean that
> the i-team would have to provide manpages, but I don't think that'd be
> the case.  Can you confirm?)

I believe Volatile interfaces (as well as Uncommitted and Committed
ones) are supposed to have manpages.  Only private interfaces can
avoid manpage documentation, I believe.

Brian