>>> 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
