Explanatory documentation what is "stable" in which case #4068

Closed
michaelrsweet opened this Issue May 3, 2012 · 3 comments

Comments

Projects
None yet
1 participant
Collaborator

michaelrsweet commented May 3, 2012

Version: 1.6-feature
CUPS.org User: jsmeix.suse

I would appreciate it, if the CUPS documentation
provides explanatory background information
how this and that is meant in CUPS in particular

  • what is a stable interface
  • what is not stable in case of minor release updates
  • what is not stable in case of patch release updates
  • what is not stable in any case (i.e. what is an implementation
    detail, in particular what is "private" e.g. private APIs)

See the "incorrect permissions on dnssd and lpd" mail thread
on the cups-bugs@easysw.com mailing list dated April 2012,
in particular:

http://www.cups.org/newsgroups.php?s1+gcups.bugs+v8+T0+Q%22incorrect+permissions+on+dnssd+and+lpd%22

Collaborator

michaelrsweet commented May 3, 2012

CUPS.org User: mike

From the thread:

  1. What is a Stable Interface?

For C APIs, anything that is documented in the online help and public header files is a stable interface unless it is specifically marked as "deprecated", in which case that API should not be used unless necessary.

For program interfaces (e.g. the filter and backend interface), the interface in any production release of CUPS is stable. However, the interface is only stable from the standpoint of the program being invoked, not for third-party applications that might try to simulate it. For example, CUPS has added new environment variables and standard file descriptors to the CUPS filter and backend interface since the original 1.0 release. CUPS 1.0 filters and backends continue to work in the current release of CUPS, however a third-party application written for the CUPS 1.0 interface cannot run other CUPS filters and backends directly that were written for a later release of CUPS.

  1. What is not stable in case of minor release updates

If you are referring to "patch" releases (CUPS major.minor.patch), we do not add new interfaces (or change existing interfaces) in patch releases. Except in extraodinary circumstances, only a "feature" release (CUPS major.minor.0) may contain new interfaces.

  1. What is not stable in any case (i.e. what is an implementation detail, in particular what is "private" e.g. private APIs)

Anything that is not specifically documented is not stable. For example, the location and format of the job data and control files and various cache files cupsd uses are not stable (and have changed many times).

CUPS configuration file formats are generally stable, however there are serious dangers involved with hand-editing some files (e.g. printers.conf and classes.conf) while cupsd is running, and those dangers are displayed prominently in the online help, man pages, and at the top of the corresponding files.

For C APIs, any function, constant, structure, union, type, or macro prefixed with an underscore is a private interface or implementation detail. These may be defined in a private header (whose name contains "-private"). These must NEVER be used by third-party software as private APIs are guaranteed to change between CUPS feature releases and may change even between patch releases.

Collaborator

michaelrsweet commented May 4, 2012

CUPS.org User: jsmeix.suse

More from the thread regarding
2. What is not stable in case of minor release updates:

Is it possible to provide some explanatory information what
such "extraodinary circumstances" might be?

For example, we found a bug in how IPP collections were handled
in CUPS 1.4.3 and earlier that required a minor API change
in 1.4.4: we added a reference count to the ipp_t structure.
This potentially caused a memory leak for existing programs
that did not "delete" the ipp_t structure added to a collection,
but fortunately their use is rare in CUPS-based programs, even
today.

Collaborator

michaelrsweet commented May 22, 2012

CUPS.org User: mike

Fixed in Subversion repository.

I ended up revising the CUPS Developer Guide significantly; there will be additional links to this content added to the web site and key developer documents as I do the final documentation sweep...

michaelrsweet added this to the Stable milestone Mar 17, 2016

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment